diff options
Diffstat (limited to 'Documentation')
40 files changed, 2671 insertions, 570 deletions
diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX index 299615d821a..c3014df066c 100644 --- a/Documentation/00-INDEX +++ b/Documentation/00-INDEX @@ -262,6 +262,8 @@ mtrr.txt - how to use PPro Memory Type Range Registers to increase performance. mutex-design.txt - info on the generic mutex subsystem. +namespaces/ + - directory with various information about namespaces nbd.txt - info on a TCP implementation of a network block device. netlabel/ diff --git a/Documentation/ABI/testing/sysfs-kernel-uids b/Documentation/ABI/testing/sysfs-kernel-uids new file mode 100644 index 00000000000..648d65dbc0e --- /dev/null +++ b/Documentation/ABI/testing/sysfs-kernel-uids @@ -0,0 +1,14 @@ +What: /sys/kernel/uids/<uid>/cpu_shares +Date: December 2007 +Contact: Dhaval Giani <dhaval@linux.vnet.ibm.com> + Srivatsa Vaddagiri <vatsa@linux.vnet.ibm.com> +Description: + The /sys/kernel/uids/<uid>/cpu_shares tunable is used + to set the cpu bandwidth a user is allowed. This is a + propotional value. What that means is that if there + are two users logged in, each with an equal number of + shares, then they will get equal CPU bandwidth. Another + example would be, if User A has shares = 1024 and user + B has shares = 2048, User B will get twice the CPU + bandwidth user A will. For more details refer + Documentation/sched-design-CFS.txt diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index 054a7ecf64c..4953bc25872 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -11,7 +11,7 @@ DOCBOOKS := wanbook.xml z8530book.xml mcabook.xml videobook.xml \ procfs-guide.xml writing_usb_driver.xml \ kernel-api.xml filesystems.xml lsm.xml usb.xml \ gadget.xml libata.xml mtdnand.xml librs.xml rapidio.xml \ - genericirq.xml s390-drivers.xml + genericirq.xml s390-drivers.xml uio-howto.xml ### # The build process is as follows (targets): diff --git a/Documentation/DocBook/uio-howto.tmpl b/Documentation/DocBook/uio-howto.tmpl index c119484258b..fdd7f4f887b 100644 --- a/Documentation/DocBook/uio-howto.tmpl +++ b/Documentation/DocBook/uio-howto.tmpl @@ -30,6 +30,12 @@ <revhistory> <revision> + <revnumber>0.4</revnumber> + <date>2007-11-26</date> + <authorinitials>hjk</authorinitials> + <revremark>Removed section about uio_dummy.</revremark> + </revision> + <revision> <revnumber>0.3</revnumber> <date>2007-04-29</date> <authorinitials>hjk</authorinitials> @@ -94,6 +100,26 @@ interested in translating it, please email me user space. This simplifies development and reduces the risk of serious bugs within a kernel module. </para> + <para> + Please note that UIO is not an universal driver interface. Devices + that are already handled well by other kernel subsystems (like + networking or serial or USB) are no candidates for an UIO driver. + Hardware that is ideally suited for an UIO driver fulfills all of + the following: + </para> +<itemizedlist> +<listitem> + <para>The device has memory that can be mapped. The device can be + controlled completely by writing to this memory.</para> +</listitem> +<listitem> + <para>The device usually generates interrupts.</para> +</listitem> +<listitem> + <para>The device does not fit into one of the standard kernel + subsystems.</para> +</listitem> +</itemizedlist> </sect1> <sect1 id="thanks"> @@ -174,8 +200,9 @@ interested in translating it, please email me For cards that don't generate interrupts but need to be polled, there is the possibility to set up a timer that triggers the interrupt handler at configurable time intervals. - See <filename>drivers/uio/uio_dummy.c</filename> for an - example of this technique. + This interrupt simulation is done by calling + <function>uio_event_notify()</function> + from the timer's event handler. </para> <para> @@ -263,63 +290,11 @@ offset = N * getpagesize(); </sect1> </chapter> -<chapter id="using-uio_dummy" xreflabel="Using uio_dummy"> -<?dbhtml filename="using-uio_dummy.html"?> -<title>Using uio_dummy</title> - <para> - Well, there is no real use for uio_dummy. Its only purpose is - to test most parts of the UIO system (everything except - hardware interrupts), and to serve as an example for the - kernel module that you will have to write yourself. - </para> - -<sect1 id="what_uio_dummy_does"> -<title>What uio_dummy does</title> - <para> - The kernel module <filename>uio_dummy.ko</filename> creates a - device that uses a timer to generate periodic interrupts. The - interrupt handler does nothing but increment a counter. The - driver adds two custom attributes, <varname>count</varname> - and <varname>freq</varname>, that appear under - <filename>/sys/devices/platform/uio_dummy/</filename>. - </para> - - <para> - The attribute <varname>count</varname> can be read and - written. The associated file - <filename>/sys/devices/platform/uio_dummy/count</filename> - appears as a normal text file and contains the total number of - timer interrupts. If you look at it (e.g. using - <function>cat</function>), you'll notice it is slowly counting - up. - </para> - - <para> - The attribute <varname>freq</varname> can be read and written. - The content of - <filename>/sys/devices/platform/uio_dummy/freq</filename> - represents the number of system timer ticks between two timer - interrupts. The default value of <varname>freq</varname> is - the value of the kernel variable <varname>HZ</varname>, which - gives you an interval of one second. Lower values will - increase the frequency. Try the following: - </para> -<programlisting format="linespecific"> -cd /sys/devices/platform/uio_dummy/ -echo 100 > freq -</programlisting> - <para> - Use <function>cat count</function> to see how the interrupt - frequency changes. - </para> -</sect1> -</chapter> - <chapter id="custom_kernel_module" xreflabel="Writing your own kernel module"> <?dbhtml filename="custom_kernel_module.html"?> <title>Writing your own kernel module</title> <para> - Please have a look at <filename>uio_dummy.c</filename> as an + Please have a look at <filename>uio_cif.c</filename> as an example. The following paragraphs explain the different sections of this file. </para> @@ -354,9 +329,8 @@ See the description below for details. interrupt, it's your modules task to determine the irq number during initialization. If you don't have a hardware generated interrupt but want to trigger the interrupt handler in some other way, set -<varname>irq</varname> to <varname>UIO_IRQ_CUSTOM</varname>. The -uio_dummy module does this as it triggers the event mechanism in a timer -routine. If you had no interrupt at all, you could set +<varname>irq</varname> to <varname>UIO_IRQ_CUSTOM</varname>. +If you had no interrupt at all, you could set <varname>irq</varname> to <varname>UIO_IRQ_NONE</varname>, though this rarely makes sense. </para></listitem> diff --git a/Documentation/i2c/summary b/Documentation/i2c/summary index 003c7319b8c..13ab076dcd9 100644 --- a/Documentation/i2c/summary +++ b/Documentation/i2c/summary @@ -1,5 +1,3 @@ -This is an explanation of what i2c is, and what is supported in this package. - I2C and SMBus ============= @@ -33,52 +31,17 @@ When we talk about I2C, we use the following terms: Client An Algorithm driver contains general code that can be used for a whole class -of I2C adapters. Each specific adapter driver depends on one algorithm -driver. +of I2C adapters. Each specific adapter driver either depends on one algorithm +driver, or includes its own implementation. A Driver driver (yes, this sounds ridiculous, sorry) contains the general code to access some type of device. Each detected device gets its own data in the Client structure. Usually, Driver and Client are more closely integrated than Algorithm and Adapter. -For a given configuration, you will need a driver for your I2C bus (usually -a separate Adapter and Algorithm driver), and drivers for your I2C devices -(usually one driver for each device). There are no I2C device drivers -in this package. See the lm_sensors project http://www.lm-sensors.nu -for device drivers. +For a given configuration, you will need a driver for your I2C bus, and +drivers for your I2C devices (usually one driver for each device). At this time, Linux only operates I2C (or SMBus) in master mode; you can't use these APIs to make a Linux system behave as a slave/device, either to speak a custom protocol or to emulate some other device. - - -Included Bus Drivers -==================== -Note that only stable drivers are patched into the kernel by 'mkpatch'. - - -Base modules ------------- - -i2c-core: The basic I2C code, including the /proc/bus/i2c* interface -i2c-dev: The /dev/i2c-* interface -i2c-proc: The /proc/sys/dev/sensors interface for device (client) drivers - -Algorithm drivers ------------------ - -i2c-algo-bit: A bit-banging algorithm -i2c-algo-pcf: A PCF 8584 style algorithm -i2c-algo-ibm_ocp: An algorithm for the I2C device in IBM 4xx processors (NOT BUILT BY DEFAULT) - -Adapter drivers ---------------- - -i2c-elektor: Elektor ISA card (uses i2c-algo-pcf) -i2c-elv: ELV parallel port adapter (uses i2c-algo-bit) -i2c-pcf-epp: PCF8584 on a EPP parallel port (uses i2c-algo-pcf) (NOT mkpatched) -i2c-philips-par: Philips style parallel port adapter (uses i2c-algo-bit) -i2c-adap-ibm_ocp: IBM 4xx processor I2C device (uses i2c-algo-ibm_ocp) (NOT BUILT BY DEFAULT) -i2c-pport: Primitive parallel port adapter (uses i2c-algo-bit) -i2c-velleman: Velleman K8000 parallel port adapter (uses i2c-algo-bit) - diff --git a/Documentation/ja_JP/HOWTO b/Documentation/ja_JP/HOWTO index d9d832c010e..488c77fa3aa 100644 --- a/Documentation/ja_JP/HOWTO +++ b/Documentation/ja_JP/HOWTO @@ -11,14 +11,14 @@ for non English (read: Japanese) speakers and is not intended as a fork. So if you have any comments or updates for this file, please try to update the original English file first. -Last Updated: 2007/09/23 +Last Updated: 2007/11/16 ================================== これは、 -linux-2.6.23/Documentation/HOWTO +linux-2.6.24/Documentation/HOWTO の和訳です。 翻訳団体： JF プロジェクト < http://www.linux.or.jp/JF/ > -翻訳日： 2007/09/19 +翻訳日： 2007/11/10 翻訳者： Tsugikazu Shibata <tshibata at ab dot jp dot nec dot com> 校正者： 松倉さん <nbh--mats at nifty dot com> 小林 雅典さん (Masanori Kobayasi) <zap03216 at nifty dot ne dot jp> @@ -110,7 +110,7 @@ Linux カーネルソースツリーは幅広い範囲のドキュメントを 新しいドキュメントファイルも追加することを勧めます。 カーネルの変更が、カーネルがユーザ空間に公開しているインターフェイスの 変更を引き起こす場合、その変更を説明するマニュアルページのパッチや情報 -をマニュアルページのメンテナ mtk-manpages@gmx.net に送ることを勧めま +をマニュアルページのメンテナ mtk.manpages@gmail.com に送ることを勧めま す。 以下はカーネルソースツリーに含まれている読んでおくべきファイルの一覧で diff --git a/Documentation/kernel-parameters.txt b/Documentation/kernel-parameters.txt index 33121d6c827..c4178778e7f 100644 --- a/Documentation/kernel-parameters.txt +++ b/Documentation/kernel-parameters.txt @@ -527,29 +527,30 @@ and is between 256 and 4096 characters. It is defined in the file Format: <area>[,<node>] See also Documentation/networking/decnet.txt. - default_blu= [VT] + vt.default_blu= [VT] Format: <blue0>,<blue1>,<blue2>,...,<blue15> Change the default blue palette of the console. This is a 16-member array composed of values ranging from 0-255. - default_grn= [VT] + vt.default_grn= [VT] Format: <green0>,<green1>,<green2>,...,<green15> Change the default green palette of the console. This is a 16-member array composed of values ranging from 0-255. - default_red= [VT] + vt.default_red= [VT] Format: <red0>,<red1>,<red2>,...,<red15> Change the default red palette of the console. This is a 16-member array composed of values ranging from 0-255. - default_utf8= [VT] + vt.default_utf8= + [VT] Format=<0|1> Set system-wide default UTF-8 mode for all tty's. - Default is 0 and by setting to 1, it enables UTF-8 - mode for all newly opened or allocated terminals. + Default is 1, i.e. UTF-8 mode is enabled for all + newly opened terminals. dhash_entries= [KNL] Set number of hash buckets for dentry cache. @@ -882,6 +883,14 @@ and is between 256 and 4096 characters. It is defined in the file lapic_timer_c2_ok [X86-32,x86-64,APIC] trust the local apic timer in C2 power state. + libata.dma= [LIBATA] DMA control + libata.dma=0 Disable all PATA and SATA DMA + libata.dma=1 PATA and SATA Disk DMA only + libata.dma=2 ATAPI (CDROM) DMA only + libata.dma=4 Compact Flash DMA only + Combinations also work, so libata.dma=3 enables DMA + for disks and CDROMs, but not CFs. + libata.noacpi [LIBATA] Disables use of ACPI in libata suspend/resume when set. Format: <int> diff --git a/Documentation/ko_KR/HOWTO b/Documentation/ko_KR/HOWTO index b51d7ca842b..029fca914c0 100644 --- a/Documentation/ko_KR/HOWTO +++ b/Documentation/ko_KR/HOWTO @@ -1,6 +1,6 @@ NOTE: This is a version of Documentation/HOWTO translated into korean -This document is maintained by minchan Kim < minchan.kim@gmail.com> +This document is maintained by minchan Kim <minchan.kim@gmail.com> If you find any difference between this document and the original file or a problem with the translation, please contact the maintainer of this file. @@ -14,7 +14,7 @@ try to update the original English file first. Documentation/HOWTO 의 한글 번역입니다. -역자： 김민찬 <minchan.kim@gmail.com > +역자： 김민찬 <minchan.kim@gmail.com> 감수： 이제이미 <jamee.lee@samsung.com> ================================== @@ -23,11 +23,11 @@ Documentation/HOWTO 이 문서는 커널 개발에 있어 가장 중요한 문서이다. 이 문서는 리눅스 커널 개발자가 되는 법과 리눅스 커널 개발 커뮤니티와 일하는 -법을 담고있다. 커널 프로그래밍의기술적인 측면과 관련된 내용들은 -포함하지 않으려고 하였지만 올바으로 여러분을 안내하는 데 도움이 +법을 담고있다. 커널 프로그래밍의 기술적인 측면과 관련된 내용들은 +포함하지 않으려고 하였지만 올바른 길로 여러분을 안내하는 데는 도움이 될 것이다. -이 문서에서 오래된 것을 발견하면 문서의 아래쪽에 나열된 메인트너에게 +이 문서에서 오래된 것을 발견하면 문서의 아래쪽에 나열된 메인테이너에게 패치를 보내달라. @@ -36,12 +36,12 @@ Documentation/HOWTO 자, 여러분은 리눅스 커널 개발자가 되는 법을 배우고 싶은가? 아니면 상사로부터"이 장치를 위한 리눅스 드라이버를 작성하시오"라는 말을 -들었는가? 이 문서는 여러분이 겪게 될 과정과 커뮤니티와 일하는 법을 -조언하여 여러분의 목적을 달성하기 위해 필요한 것 모두를 알려주는 -것이다. +들었는가? 이 문서의 목적은 여러분이 겪게 될 과정과 커뮤니티와 협력하는 +법을 조언하여 여러분의 목적을 달성하기 위해 필요한 것 모두를 알려주기 +위함이다. -커널은 대부분은 C로 작성되었어고 몇몇 아키텍쳐의 의존적인 부분은 -어셈블리로 작성되었다. 커널 개발을 위해 C를 잘 이해하고 있어야 한다. +커널은 대부분은 C로 작성되어 있고 몇몇 아키텍쳐의 의존적인 부분은 +어셈블리로 작성되어 있다. 커널 개발을 위해 C를 잘 이해하고 있어야 한다. 여러분이 특정 아키텍쳐의 low-level 개발을 할 것이 아니라면 어셈블리(특정 아키텍쳐)는 잘 알아야 할 필요는 없다. 다음의 참고서적들은 기본에 충실한 C 교육이나 수년간의 경험에 견주지는 @@ -59,11 +59,11 @@ Documentation/HOWTO 어떤 참고문서도 있지 않다. 정보를 얻기 위해서는 gcc info (`info gcc`)페이지를 살펴보라. -여러분은 기존의 개발 커뮤니티와 일하는 법을 배우려고 하고 있다는 것을 -기억하라. 코딩, 스타일, 절차에 관한 훌륭한 표준을 가진 사람들이 모인 +여러분은 기존의 개발 커뮤니티와 협력하는 법을 배우려고 하고 있다는 것을 +기억하라. 코딩, 스타일, 함수에 관한 훌륭한 표준을 가진 사람들이 모인 다양한 그룹이 있다. 이 표준들은 오랜동안 크고 지역적으로 분산된 팀들에 -의해 가장 좋은 방법으로 일하기위하여 찾은 것을 기초로 만들어져왔다. -그 표준들은 문서화가 잘 되어 있기 때문에 가능한한 미리 많은 표준들에 +의해 가장 좋은 방법으로 일하기 위하여 찾은 것을 기초로 만들어져 왔다. +그 표준들은 문서화가 잘 되어있기 때문에 가능한한 미리 많은 표준들에 관하여 배우려고 시도하라. 다른 사람들은 여러분이나 여러분의 회사가 일하는 방식에 적응하는 것을 원하지는 않는다. @@ -73,7 +73,7 @@ Documentation/HOWTO 리눅스 커널 소스 코드는 GPL로 배포(release)되었다. 소스트리의 메인 디렉토리에 있는 라이센스에 관하여 상세하게 쓰여 있는 COPYING이라는 -파일을 봐라.여러분이 라이센스에 관한 더 깊은 문제를 가지고 있다면 +파일을 봐라. 여러분이 라이센스에 관한 더 깊은 문제를 가지고 있다면 리눅스 커널 메일링 리스트에 묻지말고 변호사와 연락하라. 메일링 리스트들에 있는 사람들은 변호사가 아니기 때문에 법적 문제에 관하여 그들의 말에 의지해서는 안된다. @@ -85,12 +85,12 @@ GPL에 관한 잦은 질문들과 답변들은 다음을 참조하라. 문서 ---- -리눅스 커널 소스 트리는 커널 커뮤니티와 일하는 법을 배우기 위한 많은 -귀중한 문서들을 가지고 있다. 새로운 기능들이 커널에 들어가게 될 때, +리눅스 커널 소스 트리는 커널 커뮤니티와 협력하는 법을 배우기위해 훌륭한 +다양한 문서들을 가지고 있다. 새로운 기능들이 커널에 들어가게 될 때, 그 기능을 어떻게 사용하는지에 관한 설명을 위하여 새로운 문서 파일을 추가하는 것을 권장한다. 커널이 유저스페이스로 노출하는 인터페이스를 변경하게 되면 변경을 설명하는 메뉴얼 페이지들에 대한 패치나 정보를 -mtk-manpages@gmx.net의 메인트너에게 보낼 것을 권장한다. +mtk.manpages@gmail.com의 메인테이너에게 보낼 것을 권장한다. 다음은 커널 소스 트리에 있는 읽어야 할 파일들의 리스트이다. README @@ -105,7 +105,7 @@ mtk-manpages@gmx.net의 메인트너에게 보낼 것을 권장한다. Documentation/CodingStyle 이 문서는 리눅스 커널 코딩 스타일과 그렇게 한 몇몇 이유를 설명한다. 모든 새로운 코드는 이 문서에 가이드라인들을 따라야 한다. 대부분의 - 메인트너들은 이 규칙을 따르는 패치들만을 받아들일 것이고 많은 사람들이 + 메인테이너들은 이 규칙을 따르는 패치들만을 받아들일 것이고 많은 사람들이 그 패치가 올바른 스타일일 경우만 코드를 검토할 것이다. Documentation/SubmittingPatches @@ -115,9 +115,10 @@ mtk-manpages@gmx.net의 메인트너에게 보낼 것을 권장한다. - Email 내용들 - Email 양식 - 그것을 누구에게 보낼지 - 이러한 규칙들을 따르는 것이 성공을 보장하진 않는다(왜냐하면 모든 - 패치들은 내용과 스타일에 관하여 면밀히 검토되기 때문이다). - 그러나 규칙을 따르지 않는다면 거의 성공하지도 못할 것이다. + 이러한 규칙들을 따르는 것이 성공(역자주: 패치가 받아들여 지는 것)을 + 보장하진 않는다(왜냐하면 모든 패치들은 내용과 스타일에 관하여 + 면밀히 검토되기 때문이다). 그러나 규칙을 따르지 않는다면 거의 + 성공하지도 못할 것이다. 올바른 패치들을 만드는 법에 관한 훌륭한 다른 문서들이 있다. "The Perfect Patch" @@ -126,13 +127,13 @@ mtk-manpages@gmx.net의 메인트너에게 보낼 것을 권장한다. http://linux.yyz.us/patch-format.html Documentation/stable_api_nonsense.txt - 이 문서는 의도적으로 커널이 변하지 않는 API를 갖지 않도록 결정한 + 이 문서는 의도적으로 커널이 불변하는 API를 갖지 않도록 결정한 이유를 설명하며 다음과 같은 것들을 포함한다. - 서브시스템 shim-layer(호환성을 위해?) - - 운영 체제들 간의 드라이버 이식성 + - 운영체제들간의 드라이버 이식성 - 커널 소스 트리내에 빠른 변화를 늦추는 것(또는 빠른 변화를 막는 것) 이 문서는 리눅스 개발 철학을 이해하는데 필수적이며 다른 운영체제에서 - 리눅스로 옮겨오는 사람들에게는 매우 중요하다. + 리눅스로 전향하는 사람들에게는 매우 중요하다. Documentation/SecurityBugs @@ -141,10 +142,10 @@ mtk-manpages@gmx.net의 메인트너에게 보낼 것을 권장한다. 도와 달라. Documentation/ManagementStyle - 이 문서는 리눅스 커널 메인트너들이 어떻게 그들의 방법론의 정신을 - 어떻게 공유하고 운영하는지를 설명한다. 이것은 커널 개발에 입문하는 + 이 문서는 리눅스 커널 메인테이너들이 그들의 방법론에 녹아 있는 + 정신을 어떻게 공유하고 운영하는지를 설명한다. 이것은 커널 개발에 입문하는 모든 사람들(또는 커널 개발에 작은 호기심이라도 있는 사람들)이 - 읽어야 할 중요한 문서이다. 왜냐하면 이 문서는 커널 메인트너들의 + 읽어야 할 중요한 문서이다. 왜냐하면 이 문서는 커널 메인테이너들의 독특한 행동에 관하여 흔히 있는 오해들과 혼란들을 해소하고 있기 때문이다. @@ -160,7 +161,7 @@ mtk-manpages@gmx.net의 메인트너에게 보낼 것을 권장한다. Documentation/applying-patches.txt 패치가 무엇이며 그것을 커널의 다른 개발 브랜치들에 어떻게 - 적용하는지에 관하여 자세히 설명 하고 있는 좋은 입문서이다. + 적용하는지에 관하여 자세히 설명하고 있는 좋은 입문서이다. 커널은 소스 코드 그 자체에서 자동적으로 만들어질 수 있는 많은 문서들을 가지고 있다. 이것은 커널 내의 API에 대한 모든 설명, 그리고 락킹을 @@ -192,7 +193,7 @@ Documentation/DocBook/ 디렉토리 내에서 만들어지며 PDF, Postscript, H 여러분이 어디서 시작해야 할진 모르지만 커널 개발 커뮤니티에 참여할 수 있는 일들을 찾길 원한다면 리눅스 커널 Janitor 프로젝트를 살펴봐라. http://janitor.kernelnewbies.org/ -그곳은 시작하기에 아주 딱 좋은 곳이다. 그곳은 리눅스 커널 소스 트리내에 +그곳은 시작하기에 훌륭한 장소이다. 그곳은 리눅스 커널 소스 트리내에 간단히 정리되고 수정될 수 있는 문제들에 관하여 설명한다. 여러분은 이 프로젝트를 대표하는 개발자들과 일하면서 자신의 패치를 리눅스 커널 트리에 반영하기 위한 기본적인 것들을 배우게 될것이며 여러분이 아직 아이디어를 @@ -212,7 +213,7 @@ Documentation/DocBook/ 디렉토리 내에서 만들어지며 PDF, Postscript, H 것은 Linux Cross-Reference project이며 그것은 자기 참조 방식이며 소스코드를 인덱스된 웹 페이지들의 형태로 보여준다. 최신의 멋진 커널 코드 저장소는 다음을 통하여 참조할 수 있다. - http://sosdg.org/~coywolf/lxr/ + http://users.sosdg.org/~qiyong/lxr/ 개발 프로세스 @@ -233,44 +234,45 @@ Documentation/DocBook/ 디렉토리 내에서 만들어지며 PDF, Postscript, H 2.6.x 커널들은 Linux Torvalds가 관리하며 kernel.org의 pub/linux/kernel/v2.6/ 디렉토리에서 참조될 수 있다.개발 프로세스는 다음과 같다. - 새로운 커널이 배포되자마자 2주의 시간이 주어진다. 이 기간동은 - 메인트너들은 큰 diff들을 Linus에게 제출할 수 있다. 대개 이 패치들은 + 메인테이너들은 큰 diff들을 Linus에게 제출할 수 있다. 대개 이 패치들은 몇 주 동안 -mm 커널내에 이미 있었던 것들이다. 큰 변경들을 제출하는 데 선호되는 방법은 git(커널의 소스 관리 툴, 더 많은 정보들은 http://git.or.cz/ - 에서 참조할 수 있다)를 사용하는 것이지만 순수한 패치파일의 형식으로 보내도 + 에서 참조할 수 있다)를 사용하는 것이지만 순수한 패치파일의 형식으로 보내는 것도 무관하다. - 2주 후에 -rc1 커널이 배포되며 지금부터는 전체 커널의 안정성에 영향을 - 미칠수 있는 새로운 기능들을 포함하지 않는 패치들만을 추가될 수 있다. + 미칠수 있는 새로운 기능들을 포함하지 않는 패치들만이 추가될 수 있다. 완전히 새로운 드라이버(혹은 파일시스템)는 -rc1 이후에만 받아들여진다는 것을 기억해라. 왜냐하면 변경이 자체내에서만 발생하고 추가된 코드가 드라이버 외부의 다른 부분에는 영향을 주지 않으므로 그런 변경은 - 퇴보(regression)를 일으킬 만한 위험을 가지고 있지 않기 때문이다. -rc1이 + 회귀(역자주: 이전에는 존재하지 않았지만 새로운 기능추가나 변경으로 인해 + 생겨난 버그)를 일으킬 만한 위험을 가지고 있지 않기 때문이다. -rc1이 배포된 이후에 git를 사용하여 패치들을 Linus에게 보낼수 있지만 패치들은 공식적인 메일링 리스트로 보내서 검토를 받을 필요가 있다. - - 새로운 -rc는 Linus는 현재 git tree가 테스트 하기에 충분히 안정된 상태에 + - 새로운 -rc는 Linus가 현재 git tree가 테스트 하기에 충분히 안정된 상태에 있다고 판단될 때마다 배포된다. 목표는 새로운 -rc 커널을 매주 배포하는 것이다. - - 이러한 프로세스는 커널이 "준비"되었다고 여겨질때까지 계속된다. + - 이러한 프로세스는 커널이 "준비(ready)"되었다고 여겨질때까지 계속된다. 프로세스는 대체로 6주간 지속된다. - - 각 -rc 배포에 있는 알려진 퇴보의 목록들은 다음 URI에 남겨진다. + - 각 -rc 배포에 있는 알려진 회귀의 목록들은 다음 URI에 남겨진다. http://kernelnewbies.org/known_regressions 커널 배포에 있어서 언급할만한 가치가 있는 리눅스 커널 메일링 리스트의 Andrew Morton의 글이 있다. - "커널이 언제 배포될지는 아무로 모른다. 왜냐하면 배포는 알려진 + "커널이 언제 배포될지는 아무도 모른다. 왜냐하면 배포는 알려진 버그의 상황에 따라 배포되는 것이지 미리정해 놓은 시간에 따라 - 배포되는 것은 아니기 때문이다." + 배포되는 것은 아니기 때문이다." 2.6.x.y - 안정 커널 트리 ------------------------ 4 자리 숫자로 이루어진 버젼의 커널들은 -stable 커널들이다. 그것들은 2.6.x -커널에서 발견된 큰 퇴보들이나 보안 문제들 중 비교적 작고 중요한 수정들을 +커널에서 발견된 큰 회귀들이나 보안 문제들 중 비교적 작고 중요한 수정들을 포함한다. 이것은 가장 최근의 안정적인 커널을 원하는 사용자에게 추천되는 브랜치이며, -개발/실험적 버젼을 테스트하는 것을 돕는데는 별로 관심이 없다. +개발/실험적 버젼을 테스트하는 것을 돕고자 하는 사용자들과는 별로 관련이 없다. -어떤 2.6.x.y 커널도 사용가능하지 않다면 그때는 가장 높은 숫자의 2.6.x +어떤 2.6.x.y 커널도 사용할 수 없다면 그때는 가장 높은 숫자의 2.6.x 커널이 현재의 안정 커널이다. 2.6.x.y는 "stable" 팀<stable@kernel.org>에 의해 관리되며 거의 매번 격주로 @@ -294,7 +296,7 @@ Andrew Morton에 의해 배포된 실험적인 커널 패치들이다. Andrew는 서브시스템 커널 트리와 패치들을 가져와서 리눅스 커널 메일링 리스트로 온 많은 패치들과 한데 묶는다. 이 트리는 새로운 기능들과 패치들을 위한 장소를 제공하는 역할을 한다. 하나의 패치가 -mm에 한동안 있으면서 그 가치가 -증명되게 되면 Andrew나 서브시스템 메인트너는 그것을 메인라인에 포함시키기 +증명되게 되면 Andrew나 서브시스템 메인테이너는 그것을 메인라인에 포함시키기 위하여 Linus에게 보낸다. 커널 트리에 포함하고 싶은 모든 새로운 패치들은 Linus에게 보내지기 전에 @@ -327,7 +329,7 @@ Andrew Morton에 의해 배포된 실험적인 커널 패치들이다. Andrew는 - ACPI development tree, Len Brown <len.brown@intel.com > git.kernel.org:/pub/scm/linux/kernel/git/lenb/linux-acpi-2.6.git - - Block development tree, Jens Axboe <axboe@suse.de> + - Block development tree, Jens Axboe <jens.axboe@oracle.com> git.kernel.org:/pub/scm/linux/kernel/git/axboe/linux-2.6-block.git - DRM development tree, Dave Airlie <airlied@linux.ie> @@ -367,8 +369,8 @@ bugzilla.kernel.org는 리눅스 커널 개발자들이 커널의 버그를 추 kernel bugzilla를 사용하는 자세한 방법은 다음을 참조하라. http://test.kernel.org/bugzilla/faq.html -메인 커널 소스 디렉토리에 있는 REPORTING-BUGS 파일은 커널 버그일 것 같은 -것을 보고하는는 법에 관한 좋은 템플릿이고 문제를 추적하기 위해서 커널 +메인 커널 소스 디렉토리에 있는 REPORTING-BUGS 파일은 커널 버그라고 생각되는 +것을 보고하는 방법에 관한 좋은 템플릿이며 문제를 추적하기 위해서 커널 개발자들이 필요로 하는 정보가 무엇들인지를 상세히 설명하고 있다. @@ -383,7 +385,7 @@ kernel bugzilla를 사용하는 자세한 방법은 다음을 참조하라. 점수를 얻을 수 있는 가장 좋은 방법중의 하나이다. 왜냐하면 많은 사람들은 다른 사람들의 버그들을 수정하기 위하여 시간을 낭비하지 않기 때문이다. -이미 보고된 버그 리포트들을 가지고 작업하기 위해서 http://bugzilla.kernelorg를 +이미 보고된 버그 리포트들을 가지고 작업하기 위해서 http://bugzilla.kernel.org를 참조하라. 여러분이 앞으로 생겨날 버그 리포트들의 조언자가 되길 원한다면 bugme-new 메일링 리스트나(새로운 버그 리포트들만이 이곳에서 메일로 전해진다) bugme-janitor 메일링 리스트(bugzilla에 모든 변화들이 여기서 메일로 전해진다) @@ -404,8 +406,8 @@ bugme-janitor 메일링 리스트(bugzilla에 모든 변화들이 여기서 메 웹상의 많은 다른 곳에도 메일링 리스트의 아카이브들이 있다. 이러한 아카이브들을 찾으려면 검색 엔진을 사용하라. 예를 들어: http://dir.gmane.org/gmane.linux.kernel -여러분이 새로운 문제에 관해 리스트에 올리기 전에 말하고 싶은 주제에 대한 -것을 아카이브에서 먼저 찾기를 강력히 권장한다. 이미 상세하게 토론된 많은 +여러분이 새로운 문제에 관해 리스트에 올리기 전에 말하고 싶은 주제에 관한 +것을 아카이브에서 먼저 찾아보기를 강력히 권장한다. 이미 상세하게 토론된 많은 것들이 메일링 리스트의 아카이브에 기록되어 있다. 각각의 커널 서브시스템들의 대부분은 자신들의 개발에 관한 노력들로 이루어진 @@ -443,7 +445,7 @@ bugme-janitor 메일링 리스트(bugzilla에 모든 변화들이 여기서 메 무엇보다도 메일링 리스트의 다른 구독자들에게 보여주려 한다는 것을 기억하라. -커뮤니티와 일하는 법 +커뮤니티와 협력하는 법 -------------------- 커널 커뮤니티의 목적은 가능한한 가장 좋은 커널을 제공하는 것이다. 여러분이 @@ -474,7 +476,7 @@ bugme-janitor 메일링 리스트(bugzilla에 모든 변화들이 여기서 메 올바른 방향의 해결책으로 이끌어갈 의지가 있다면 받아들여질 것이라는 점을 기억하라. -여러분의 첫 패치에 여러분이 수정해야하는 십여개 정도의 회신이 오는 +여러분의 첫 패치에 여러분이 수정해야하는 십여개 정도의 회신이 오는 경우도 흔하다. 이것은 여러분의 패치가 받아들여지지 않을 것이라는 것을 의미하는 것이 아니고 개인적으로 여러분에게 감정이 있어서 그러는 것도 아니다. 간단히 여러분의 패치에 제기된 문제들을 수정하고 그것을 다시 @@ -486,12 +488,12 @@ bugme-janitor 메일링 리스트(bugzilla에 모든 변화들이 여기서 메 커널 커뮤니티는 가장 전통적인 회사의 개발 환경과는 다르다. 여기에 여러분들의 문제를 피하기 위한 목록이 있다. 여러분들이 제안한 변경들에 관하여 말할 때 좋은 것들 : - - " 이것은 여러 문제들을 해겹합니다." + - "이것은 여러 문제들을 해겹합니다." - "이것은 2000 라인의 코드를 제거합니다." - "이것은 내가 말하려는 것에 관해 설명하는 패치입니다." - "나는 5개의 다른 아키텍쳐에서 그것을 테스트했슴으로..." - - "여기에 일련의 작은 패치들이 있습음로..." - - "이것은 일반적인 머신에서 성능을 향상시키므로..." + - "여기에 일련의 작은 패치들이 있슴음로..." + - "이것은 일반적인 머신에서 성능을 향상시킴으로..." 여러분들이 말할 때 피해야 할 좋지 않은 것들 : - "우리를 그것을 AIT/ptx/Solaris에서 이러한 방법으로 했다. 그러므로 그것은 좋은 것임에 틀립없다..." @@ -500,7 +502,7 @@ bugme-janitor 메일링 리스트(bugzilla에 모든 변화들이 여기서 메 - "이것은 우리의 엔터프라이즈 상품 라인을 위한 것이다." - "여기에 나의 생각을 말하고 있는 1000 페이지 설계 문서가 있다." - "나는 6달동안 이것을 했으니..." - - "여기세 5000라인 짜리 패치가 있으니..." + - "여기에 5000라인 짜리 패치가 있으니..." - "나는 현재 뒤죽박죽인 것을 재작성했다. 그리고 여기에..." - "나는 마감시한을 가지고 있으므로 이 패치는 지금 적용될 필요가 있다." @@ -510,13 +512,13 @@ bugme-janitor 메일링 리스트(bugzilla에 모든 변화들이 여기서 메 없다는 것이다. 리눅스 커널의 작업 환경에서는 단지 이메일 주소만 알수 있기 때문에 여성과 소수 민족들도 모두 받아들여진다. 국제적으로 일하게 되는 측면은 사람의 이름에 근거하여 성별을 추측할 수 없게 -하기때문에 차별을 없애는 데 도움을 준다. Andrea라는 이름을 가진 남자와 +하기때문에 차별을 없애는 데 도움을 준다. Andrea라는 이름을 가진 남자와 Pat이라는 이름을 가진 여자가 있을 수도 있는 것이다. 리눅스 커널에서 작업하며 생각을 표현해왔던 대부분의 여성들은 긍정적인 경험을 가지고 있다. 언어 장벽은 영어에 익숙하지 않은 몇몇 사람들에게 문제가 될 수도 있다. - 언어의 훌륭한 구사는 메일링 리스트에서 올바르게 자신의 생각을 +언어의 훌륭한 구사는 메일링 리스트에서 올바르게 자신의 생각을 표현하기 위하여 필요하다. 그래서 여러분은 이메일을 보내기 전에 영어를 올바르게 사용하고 있는지를 체크하는 것이 바람직하다. @@ -524,13 +526,13 @@ Pat이라는 이름을 가진 여자가 있을 수도 있는 것이다. 리눅 여러분의 변경을 나누어라 ------------------------ -리눅스 커널 커뮤니티는 한꺼번에 굉장히 큰 코드의 묶음을 쉽게 +리눅스 커널 커뮤니티는 한꺼번에 굉장히 큰 코드의 묶음(chunk)을 쉽게 받아들이지 않는다. 변경은 적절하게 소개되고, 검토되고, 각각의 부분으로 작게 나누어져야 한다. 이것은 회사에서 하는 것과는 정확히 반대되는 것이다. 여러분들의 제안은 개발 초기에 일찍이 소개되야 한다. 그래서 여러분들은 자신이 하고 있는 것에 관하여 피드백을 받을 수 있게 된다. 커뮤니티가 여러분들이 커뮤니티와 함께 일하고 있다는 것을 -느끼도록 만들고 커뮤니티가 여러분의 기능을 위한 쓰레기 장으로서 +느끼도록 만들고 커뮤니티가 여러분의 기능을 위한 쓰레기 장으로써 사용되지 않고 있다는 것을 느끼게 하자. 그러나 메일링 리스트에 한번에 50개의 이메일을 보내지는 말아라. 여러분들의 일련의 패치들은 항상 더 작아야 한다. @@ -539,7 +541,7 @@ Pat이라는 이름을 가진 여자가 있을 수도 있는 것이다. 리눅 1) 작은 패치들은 여러분의 패치들이 적용될 수 있는 확률을 높여준다. 왜냐하면 다른 사람들은 정확성을 검증하기 위하여 많은 시간과 노력을 - 들이기를 원하지 않는다. 5줄의 패치는 메인트너가 거의 몇 초간 힐끗 + 들이기를 원하지 않는다. 5줄의 패치는 메인테이너가 거의 몇 초간 힐끗 보면 적용될 수 있다. 그러나 500 줄의 패치는 정확성을 검토하기 위하여 몇시간이 걸릴 수도 있다(걸리는 시간은 패치의 크기 혹은 다른 것에 비례하여 기하급수적으로 늘어난다). @@ -558,18 +560,18 @@ Pat이라는 이름을 가진 여자가 있을 수도 있는 것이다. 리눅 간결하고 가장 뛰어난 답을 보길 원한다. 훌륭한 학생은 이것을 알고 마지막으로 답을 얻기 전 중간 과정들을 제출하진 않는다. - 커널 개발도 마찬가지이다. 메인트너들과 검토하는 사람들은 문제를 + 커널 개발도 마찬가지이다. 메인테이너들과 검토하는 사람들은 문제를 풀어나가는 과정속에 숨겨진 과정을 보길 원하진 않는다. 그들은 간결하고 멋진 답을 보길 원한다." -커뮤니티와 함께 일하며 뛰어난 답을 찾고 여러분들의 완성되지 않은 일들 -사이에 균형을 유지해야 하는 어려움이 있을 수 있다. 그러므로 프로세스의 -초반에 여러분의 일을 향상시키기위한 피드백을 얻는 것 뿐만 아니라 +커뮤니티와 협력하며 뛰어난 답을 찾는 것과 여러분들의 끝마치지 못한 작업들 +사이에 균형을 유지해야 하는 것은 어려울지도 모른다. 그러므로 프로세스의 +초반에 여러분의 작업을 향상시키기위한 피드백을 얻는 것 뿐만 아니라 여러분들의 변경들을 작은 묶음으로 유지해서 심지어는 여러분의 작업의 -모든 부분이 지금은 포함될 준비가 되어있지 않지만 작은 부분은 이미 +모든 부분이 지금은 포함될 준비가 되어있지 않지만 작은 부분은 벌써 받아들여질 수 있도록 유지하는 것이 바람직하다. -또한 완성되지 않았고 "나중에 수정될 것이다." 와 같은 것들은 포함하는 +또한 완성되지 않았고 "나중에 수정될 것이다." 와 같은 것들을 포함하는 패치들은 받아들여지지 않을 것이라는 점을 유념하라. 변경을 정당화해라 @@ -577,7 +579,7 @@ Pat이라는 이름을 가진 여자가 있을 수도 있는 것이다. 리눅 여러분들의 나누어진 패치들을 리눅스 커뮤니티가 왜 반영해야 하는지를 알도록 하는 것은 매우 중요하다. 새로운 기능들이 필요하고 유용하다는 -것은 반드시 그에 맞는 이유가 있어야 한다. +것은 반드시 그에 합당한 이유가 있어야 한다. 변경을 문서화해라 @@ -588,7 +590,7 @@ Pat이라는 이름을 가진 여자가 있을 수도 있는 것이다. 리눅 것이다. 그리고 항상 그 내용을 보길 원하는 모든 사람들을 위해 보존될 것이다. 패치는 완벽하게 다음과 같은 내용들을 포함하여 설명해야 한다. - 변경이 왜 필요한지 - - 패치에 관한 전체 설계 어프로치 + - 패치에 관한 전체 설계 접근(approach) - 구현 상세들 - 테스트 결과들 @@ -600,7 +602,7 @@ Pat이라는 이름을 가진 여자가 있을 수도 있는 것이다. 리눅 이 모든 것을 하는 것은 매우 어려운 일이다. 완벽히 소화하는 데는 적어도 몇년이 -걸릴 수도 있다. 많은 인내와 결의가 필요한 계속되는 개선의 과정이다. 그러나 +걸릴 수도 있다. 많은 인내와 결심이 필요한 계속되는 개선의 과정이다. 그러나 가능한한 포기하지 말라. 많은 사람들은 이전부터 해왔던 것이고 그 사람들도 정확하게 여러분들이 지금 서 있는 그 곳부터 시작했었다. @@ -620,4 +622,4 @@ David A. Wheeler, Junio Hamano, Michael Kerrisk, and Alex Shepard에게도 감 -메인트너: Greg Kroah-Hartman <greg@kroah.com> +메인테이너: Greg Kroah-Hartman <greg@kroah.com> diff --git a/Documentation/ko_KR/stable_api_nonsense.txt b/Documentation/ko_KR/stable_api_nonsense.txt new file mode 100644 index 00000000000..8f2b0e1d98c --- /dev/null +++ b/Documentation/ko_KR/stable_api_nonsense.txt @@ -0,0 +1,195 @@ +NOTE: +This is a version of Documentation/stable_api_nonsense.txt translated +into korean +This document is maintained by barrios <minchan.kim@gmail.com> +If you find any difference between this document and the original file or +a problem with the translation, please contact the maintainer of this file. + +Please also note that the purpose of this file is to be easier to +read for non English (read: korean) speakers and is not intended as +a fork. So if you have any comments or updates for this file please +try to update the original English file first. + +================================== +이 문서는 +Documentation/stable_api_nonsense.txt +의 한글 번역입니다. + +역자： 김민찬 <minchan.kim@gmail.com> +감수： 이제이미 <jamee.lee@samsung.com> +================================== + +리눅스 커널 드라이버 인터페이스 +(여러분들의 모든 질문에 대한 답 그리고 다른 몇가지) + +Greg Kroah-Hartman <greg@kroah.com> + +이 문서는 리눅스가 왜 바이너리 커널 인터페이스를 갖지 않는지, 왜 변하지 +않는(stable) 커널 인터페이스를 갖지 않는지를 설명하기 위해 쓰여졌다. +이 문서는 커널과 유저공간 사이의 인터페이스가 아니라 커널 내부의 +인터페이스들을 설명하고 있다는 것을 유념하라. 커널과 유저공간 사이의 +인터페이스는 응용프로그램이 사용하는 syscall 인터페이스이다. 그 인터페이스는 +오랫동안 거의 변하지 않았고 앞으로도 변하지 않을 것이다. 나는 pre 0.9에서 +만들어졌지만 최신의 2.6 커널 배포에서도 잘 동작하는 프로그램을 가지고 +있다. 이 인터페이스는 사용자와 응용프로그램 개발자들이 변하지 않을 것이라고 +여길수 있는 것이다. + + +초록 +---- +여러분은 변하지 않는 커널 인터페이스를 원한다고 생각하지만 실제로는 +그렇지 않으며 심지어는 그것을 알아채지 못한다. 여러분이 원하는 것은 +안정되게 실행되는 드라이버이며 드라이버가 메인 커널 트리에 있을 때 +그런 안정적인 드라이버를 얻을 수 있게 된다. 또한 여러분의 드라이버가 +메인 커널 트리에 있다면 다른 많은 좋은 이점들을 얻게 된다. 그러한 것들이 +리눅스를 강건하고, 안정적이며, 성숙한 운영체제로 만들어 놓음으로써 +여러분들로 하여금 바로 리눅스를 사용하게 만드는 이유이다. + + +소개 +---- + +커널 내부의 인터페이스가 바뀌는 것을 걱정하며 커널 드라이버를 작성하고 +싶어하는 사람은 정말 이상한 사람이다. 세상의 대다수의 사람들은 이 인터페이스를 +보지못할 것이며 전혀 걱정하지도 않는다. + +먼저, 나는 closed 소스, hidden 소스, binary blobs, 소스 wrappers, 또는 GPL로 +배포되었지만 소스 코드를 갖고 있지 않은 커널 드라이버들을 설명하는 어떤 다른 +용어들에 관한 어떤 법적인 문제에 관해서는 언급하지 않을 것이다. 어떤 법적인 +질문들을 가지고 있다면 변호사와 연락하라. 나는 프로그래머이므로 여기서 기술적인 +문제들만을 설명하려고 한다. (법적인 문제를 경시하는 것은 아니다. 그런 문제들은 +엄연히 현실에 있고 여러분들은 항상 그 문제들을 인식하고 있을 필요는 있다.) + +자, 두가지의 주요 주제가 있다. 바이너리 커널 인터페이스들과 변하지 않는 +커널 소스 인터페이들. 그것들은 서로 의존성을 가지고 있지만 바이너리 +문제를 먼저 풀고 넘어갈 것이다. + + + +바이너리 커널 인터페이스 +------------------------ +우리가 변하지 않는 커널 소스 인터페이스를 가지고 있다고 가정하자. 그러면 +바이너리 인터페이스 또한 자연적으로 변하지 않을까? 틀렸다. 리눅스 커널에 +관한 다음 사실들을 생각해보라. + - 여러분들이 사용하는 C 컴파일러의 버젼에 따라 다른 커널 자료 구조들은 + 다른 alignmnet들을 갖게 될것이고 다른 방법으로(함수들을 inline으로 + 했느냐, 아니냐) 다른 함수들을 포함하는 것도 가능한다. 중요한 것은 + 개별적인 함수 구성이 아니라 자료 구조 패딩이 달라진다는 점이다. + - 여러분이 선택한 커널 빌드 옵션에 따라서 커널은 다양한 것들을 가정할 + 수 있다. + - 다른 구조체들은 다른 필드들을 포함할 수 있다. + - 몇몇 함수들은 전혀 구현되지 않을 수도 있다(즉, 몇몇 lock들은 + non-SMP 빌드에서는 사라져 버릴수도 있다). + - 커널내에 메모리는 build optoin들에 따라 다른 방법으로 align될수 + 있다. + - 리눅스는 많은 다양한 프로세서 아키텍쳐에서 실행된다. 한 아키텍쳐의 + 바이너리 드라이버를 다른 아키텍쳐에서 정상적으로 실행시킬 방법은 + 없다. + +커널을 빌드했던 C 컴파일러와 정확하게 같은 것을 사용하고 정확하게 같은 +커널 구성(configuration)을 사용하여 여러분들의 모듈을 빌드하면 간단히 +많은 문제들을 해결할 수 있다. 이렇게 하는 것은 여러분들이 하나의 리눅스 +배포판의 하나의 배포 버젼을 위한 모듈만을 제공한다면 별일 아닐 것이다. +그러나 각기 다른 리눅스 배포판마다 한번씩 빌드하는 수를 각 리눅스 배포판마다 +제공하는 다른 릴리즈의 수와 곱하게 되면 이번에는 각 릴리즈들의 다른 빌드 +옵션의 악몽과 마주하게 것이다. 또한 각 리눅스 배포판들은 다른 하드웨어 +종류에(다른 프로세서 타입과 다른 옵션들) 맞춰져 있는 많은 다른 커널들을 +배포한다. 그러므로 한번의 배포에서조차 여러분들의 모듈은 여러 버젼을 +만들 필요가 있다. + +나를 믿어라. 여러분들은 이러한 종류의 배포를 지원하려고 시도한다면 시간이 +지나면 미칠지경이 될 것이다. 난 이러한 것을 오래전에 아주 어렵게 배웠다... + + + +변하지않는 커널 소스 인터페이스들 +--------------------------------- + +리눅스 커널 드라이버를 계속해서 메인 커널 트리에 반영하지 않고 +유지보수하려고 하는 사름들과 이 문제를 논의하게 되면 훨씬 더 +"논란의 여지가 많은" 주제가 될 것이다. + +리눅스 커널 개발은 끊임없이 빠른 속도로 이루어지고 있으며 결코 +느슨해진 적이 없다. 커널 개발자들이 현재 인터페이스들에서 버그를 +발견하거나 무엇인가 할수 있는 더 좋은 방법을 찾게 되었다고 하자. +그들이 발견한 것을 실행한다면 아마도 더 잘 동작하도록 현재 인터페이스들을 +수정하게 될 것이다. 그들이 그런 일을 하게되면 함수 이름들은 변하게 되고, +구조체들은 늘어나거나 줄어들게 되고, 함수 파라미터들은 재작업될 것이다. +이러한 일이 발생되면 커널 내에 이 인터페이스를 사용했던 인스턴스들이 동시에 +수정될 것이며 이러한 과정은 모든 것이 계속해서 올바르게 동작할 것이라는 +것을 보장한다. + +이러한 것의 한 예로써, 커널 내부의 USB 인터페이스들은 이 서브시스템이 +생긴 이후로 적어도 3번의 다른 재작업을 겪었다. 이 재작업들은 많은 다른 +문제들을 풀었다. + - 데이터 스트림들의 동기적인 모델에서 비동기적인 모델로의 변화. 이것은 + 많은 드라이버들의 복잡성을 줄이고 처리량을 향상시켜 현재는 거의 모든 + USB 장치들의 거의 최대 속도로 실행되고 있다. + - USB 드라이버가 USB 코어로부터 데이터 패킷들을 할당받로록 한 변경으로 + 인해서 지금의 모든 드라이버들은 많은 문서화된 데드락을 수정하기 위하여 + USB 코어에게 더 많은 정보를 제공해야만 한다. + +이것은 오랫동안 자신의 오래된 USB 인터페이스들을 유지해야 하는 closed 운영체제들과는 +완전히 반대되는 것이다. closed된 운영체제들은 새로운 개발자들에게 우연히 낡은 +인터페이스를 사용하게 할 기회를 주게되며, 적절하지 못한 방법으로 처리하게 되어 +운영체제의 안정성을 해치는 문제를 야기하게 된다. + +이 두가지의 예들 모두, 모든 개발자들은 꼭 이루어져야 하는 중요한 변화들이라고 +동의를 하였고 비교적 적은 고통으로 변경되어졌다. 리눅스가 변하지 않는 소스 +인터페이스를 고집한다면, 새로운 인터페이스가 만들어지게 되며 반면 기존의 오래된 +것들, 그리고 깨진 것들은 계속해서 유지되어야 하며 이러한 일들은 USB 개발자들에게 +또 다른 일거리를 주게 된다. 모든 리눅스 USB 개발자들에게 자신의 그들의 업무를 +마친 후 시간을 투자하여 아무 득도 없는 무료 봉사를 해달라고 하는 것은 가능성이 +희박한 일이다. + +보안 문제 역시 리눅스에게는 매우 중요하다. 보안 문제가 발견되면 그것은 +매우 짧은 시간 안에 수정된다. 보안 문제는 그 문제를 해결하기 위하여 +여러번 내부 커널 인터페이스들을 재작업하게 만들었다. 이러한 문제가 +발생하였을 때 그 인터페이스들을 사용하는 모든 드라이버들도 동시에 +수정되어 보안 문제가 앞으로 갑작스럽게 생기지는 않을 것이라는 것을 +보장한다. 내부 인터페이스들의 변경이 허락되지 않으면 이러한 종류의 보안 +문제를 수정하고 그것이 다시 발생하지 않을 것이라고 보장하는 것은 가능하지 +않을 것이다. + +커널 인터페이스들은 계속해서 정리되고 있다. 현재 인터페이스를 사용하는 +사람이 한명도 없다면 그것은 삭제된다. 이것은 커널이 가능한한 가장 작게 +유지되며 존재하는 모든 가능성이 있는 인터페이스들이 테스트된다는 것을 +보장한다(사용되지 않는 인터페이스들은 유효성 검증을 하기가 거의 불가능하다). + + +무엇을 해야 하나 +--------------- +자, 여러분이 메인 커널 트리에 있지 않은 리눅스 커널 드라이버를 가지고 +있다면 여러분은 즉, 개발자는 무엇을 해야 하나? 모든 배포판마다 다른 +커널 버젼을 위한 바이너리 드라이버를 배포하는 것은 악몽이며 계속해서 +변하고 있는 커널 인터페이스들의 맞처 유지보수하려고 시도하는 것은 힘든 +일이다. + +간단하다. 여러분의 커널 드라이버를 메인 커널 트리에 반영하라(우리는 여기서 +GPL을 따르는 배포 드라이버에 관해 얘기하고 있다는 것을 상기하라. 여러분의 +코드가 이러한 분류에 해당되지 않는다면 행운을 빈다. 여러분 스스로 어떻게든 +해야만 한다). 여러분의 드라이버가 트리에 있게되면 커널 인터페이스가 +변경되더라도 가장 먼저 커널에 변경을 가했던 사람에 의해서 수정될 것이다. +이것은 여러분의 드라이버가 여러분의 별다른 노력없이 항상 빌드가 가능하며 +동작하는 것을 보장한다. + +메인 커널 트리에 여러분의 드라이버를 반영하면 얻게 되는 장점들은 다음과 같다. + - 관리의 드는 비용(원래 개발자의)은 줄어줄면서 드라이버의 질은 향상될 것이다. + - 다른 개발자들이 여러분의 드라이버에 기능들을 추가 할 것이다. + - 다른 사람들은 여러분의 드라이버에 버그를 발견하고 수정할 것이다. + - 다른 사람들은 여러분의 드라이버의 개선점을 찾을 줄 것이다. + - 외부 인터페이스 변경으로 인해 여러분의 드라이버의 수정이 필요하다면 다른 + 사람들이 드라이버를 업데이트할 것이다. + - 여러분의 드라이버는 별다른 노력 없이 모든 리눅스 배포판에 자동적으로 + 추가될 것이다. + +리눅스는 다른 운영 체제보다 "쉽게 쓸수 있는(out of the box)" 많은 다른 장치들을 +지원하고 어떤 다른 운영 체제보다 다양한 아키텍쳐위에서 이러한 장치들을 지원하기 때문에 +이러한 증명된 개발 모델은 틀림없이 바로 가고 있는 것이다. + + + +------ + +이 문서의 초안을 검토해주고 코멘트 해준 Randy Dunlap, Andrew Morton, David Brownell, +Hanna Linder, Robert Love, 그리고 Nishanth Aravamudan에게 감사한다. diff --git a/Documentation/kobject.txt b/Documentation/kobject.txt index ca86a885ad8..bf3256e0402 100644 --- a/Documentation/kobject.txt +++ b/Documentation/kobject.txt @@ -1,289 +1,386 @@ -The kobject Infrastructure +Everything you never wanted to know about kobjects, ksets, and ktypes -Patrick Mochel <mochel@osdl.org> +Greg Kroah-Hartman <gregkh@suse.de> -Updated: 3 June 2003 +Based on an original article by Jon Corbet for lwn.net written October 1, +2003 and located at http://lwn.net/Articles/51437/ +Last updated December 19, 2007 -Copyright (c) 2003 Patrick Mochel -Copyright (c) 2003 Open Source Development Labs +Part of the difficulty in understanding the driver model - and the kobject +abstraction upon which it is built - is that there is no obvious starting +place. Dealing with kobjects requires understanding a few different types, +all of which make reference to each other. In an attempt to make things +easier, we'll take a multi-pass approach, starting with vague terms and +adding detail as we go. To that end, here are some quick definitions of +some terms we will be working with. -0. Introduction + - A kobject is an object of type struct kobject. Kobjects have a name + and a reference count. A kobject also has a parent pointer (allowing + objects to be arranged into hierarchies), a specific type, and, + usually, a representation in the sysfs virtual filesystem. -The kobject infrastructure performs basic object management that larger -data structures and subsystems can leverage, rather than reimplement -similar functionality. This functionality primarily concerns: + Kobjects are generally not interesting on their own; instead, they are + usually embedded within some other structure which contains the stuff + the code is really interested in. -- Object reference counting. -- Maintaining lists (sets) of objects. -- Object set locking. -- Userspace representation. + No structure should EVER have more than one kobject embedded within it. + If it does, the reference counting for the object is sure to be messed + up and incorrect, and your code will be buggy. So do not do this. -The infrastructure consists of a number of object types to support -this functionality. Their programming interfaces are described below -in detail, and briefly here: + - A ktype is the type of object that embeds a kobject. Every structure + that embeds a kobject needs a corresponding ktype. The ktype controls + what happens to the kobject when it is created and destroyed. -- kobjects a simple object. -- kset a set of objects of a certain type. -- ktype a set of helpers for objects of a common type. + - A kset is a group of kobjects. These kobjects can be of the same ktype + or belong to different ktypes. The kset is the basic container type for + collections of kobjects. Ksets contain their own kobjects, but you can + safely ignore that implementation detail as the kset core code handles + this kobject automatically. + When you see a sysfs directory full of other directories, generally each + of those directories corresponds to a kobject in the same kset. -The kobject infrastructure maintains a close relationship with the -sysfs filesystem. Each kobject that is registered with the kobject -core receives a directory in sysfs. Attributes about the kobject can -then be exported. Please see Documentation/filesystems/sysfs.txt for -more information. +We'll look at how to create and manipulate all of these types. A bottom-up +approach will be taken, so we'll go back to kobjects. -The kobject infrastructure provides a flexible programming interface, -and allows kobjects and ksets to be used without being registered -(i.e. with no sysfs representation). This is also described later. +Embedding kobjects -1. kobjects +It is rare for kernel code to create a standalone kobject, with one major +exception explained below. Instead, kobjects are used to control access to +a larger, domain-specific object. To this end, kobjects will be found +embedded in other structures. If you are used to thinking of things in +object-oriented terms, kobjects can be seen as a top-level, abstract class +from which other classes are derived. A kobject implements a set of +capabilities which are not particularly useful by themselves, but which are +nice to have in other objects. The C language does not allow for the +direct expression of inheritance, so other techniques - such as structure +embedding - must be used. -1.1 Description +So, for example, the UIO code has a structure that defines the memory +region associated with a uio device: +struct uio_mem { + struct kobject kobj; + unsigned long addr; + unsigned long size; + int memtype; + void __iomem *internal_addr; +}; -struct kobject is a simple data type that provides a foundation for -more complex object types. It provides a set of basic fields that -almost all complex data types share. kobjects are intended to be -embedded in larger data structures and replace fields they duplicate. +If you have a struct uio_mem structure, finding its embedded kobject is +just a matter of using the kobj member. Code that works with kobjects will +often have the opposite problem, however: given a struct kobject pointer, +what is the pointer to the containing structure? You must avoid tricks +(such as assuming that the kobject is at the beginning of the structure) +and, instead, use the container_of() macro, found in <linux/kernel.h>: -1.2 Definition + container_of(pointer, type, member) -struct kobject { - const char * k_name; - struct kref kref; - struct list_head entry; - struct kobject * parent; - struct kset * kset; - struct kobj_type * ktype; - struct sysfs_dirent * sd; - wait_queue_head_t poll; -}; +where pointer is the pointer to the embedded kobject, type is the type of +the containing structure, and member is the name of the structure field to +which pointer points. The return value from container_of() is a pointer to +the given type. So, for example, a pointer "kp" to a struct kobject +embedded within a struct uio_mem could be converted to a pointer to the +containing uio_mem structure with: -void kobject_init(struct kobject *); -int kobject_add(struct kobject *); -int kobject_register(struct kobject *); + struct uio_mem *u_mem = container_of(kp, struct uio_mem, kobj); -void kobject_del(struct kobject *); -void kobject_unregister(struct kobject *); +Programmers often define a simple macro for "back-casting" kobject pointers +to the containing type. -struct kobject * kobject_get(struct kobject *); -void kobject_put(struct kobject *); +Initialization of kobjects -1.3 kobject Programming Interface +Code which creates a kobject must, of course, initialize that object. Some +of the internal fields are setup with a (mandatory) call to kobject_init(): -kobjects may be dynamically added and removed from the kobject core -using kobject_register() and kobject_unregister(). Registration -includes inserting the kobject in the list of its dominant kset and -creating a directory for it in sysfs. + void kobject_init(struct kobject *kobj, struct kobj_type *ktype); -Alternatively, one may use a kobject without adding it to its kset's list -or exporting it via sysfs, by simply calling kobject_init(). An -initialized kobject may later be added to the object hierarchy by -calling kobject_add(). An initialized kobject may be used for -reference counting. +The ktype is required for a kobject to be created properly, as every kobject +must have an associated kobj_type. After calling kobject_init(), to +register the kobject with sysfs, the function kobject_add() must be called: -Note: calling kobject_init() then kobject_add() is functionally -equivalent to calling kobject_register(). + int kobject_add(struct kobject *kobj, struct kobject *parent, const char *fmt, ...); -When a kobject is unregistered, it is removed from its kset's list, -removed from the sysfs filesystem, and its reference count is decremented. -List and sysfs removal happen in kobject_del(), and may be called -manually. kobject_put() decrements the reference count, and may also -be called manually. +This sets up the parent of the kobject and the name for the kobject +properly. If the kobject is to be associated with a specific kset, +kobj->kset must be assigned before calling kobject_add(). If a kset is +associated with a kobject, then the parent for the kobject can be set to +NULL in the call to kobject_add() and then the kobject's parent will be the +kset itself. -A kobject's reference count may be incremented with kobject_get(), -which returns a valid reference to a kobject; and decremented with -kobject_put(). An object's reference count may only be incremented if -it is already positive. +As the name of the kobject is set when it is added to the kernel, the name +of the kobject should never be manipulated directly. If you must change +the name of the kobject, call kobject_rename(): -When a kobject's reference count reaches 0, the method struct -kobj_type::release() (which the kobject's kset points to) is called. -This allows any memory allocated for the object to be freed. + int kobject_rename(struct kobject *kobj, const char *new_name); +There is a function called kobject_set_name() but that is legacy cruft and +is being removed. If your code needs to call this function, it is +incorrect and needs to be fixed. -NOTE!!! +To properly access the name of the kobject, use the function +kobject_name(): -It is _imperative_ that you supply a destructor for dynamically -allocated kobjects to free them if you are using kobject reference -counts. The reference count controls the lifetime of the object. -If it goes to 0, then it is assumed that the object will -be freed and cannot be used. + const char *kobject_name(const struct kobject * kobj); -More importantly, you must free the object there, and not immediately -after an unregister call. If someone else is referencing the object -(e.g. through a sysfs file), they will obtain a reference to the -object, assume it's valid and operate on it. If the object is -unregistered and freed in the meantime, the operation will then -reference freed memory and go boom. +There is a helper function to both initialize and add the kobject to the +kernel at the same time, called supprisingly enough kobject_init_and_add(): -This can be prevented, in the simplest case, by defining a release -method and freeing the object from there only. Note that this will not -secure reference count/object management models that use a dual -reference count or do other wacky things with the reference count -(like the networking layer). + int kobject_init_and_add(struct kobject *kobj, struct kobj_type *ktype, + struct kobject *parent, const char *fmt, ...); +The arguments are the same as the individual kobject_init() and +kobject_add() functions described above. -1.4 sysfs -Each kobject receives a directory in sysfs. This directory is created -under the kobject's parent directory. +Uevents -If a kobject does not have a parent when it is registered, its parent -becomes its dominant kset. +After a kobject has been registered with the kobject core, you need to +announce to the world that it has been created. This can be done with a +call to kobject_uevent(): -If a kobject does not have a parent nor a dominant kset, its directory -is created at the top-level of the sysfs partition. + int kobject_uevent(struct kobject *kobj, enum kobject_action action); +Use the KOBJ_ADD action for when the kobject is first added to the kernel. +This should be done only after any attributes or children of the kobject +have been initialized properly, as userspace will instantly start to look +for them when this call happens. +When the kobject is removed from the kernel (details on how to do that is +below), the uevent for KOBJ_REMOVE will be automatically created by the +kobject core, so the caller does not have to worry about doing that by +hand. -2. ksets -2.1 Description +Reference counts -A kset is a set of kobjects that are embedded in the same type. +One of the key functions of a kobject is to serve as a reference counter +for the object in which it is embedded. As long as references to the object +exist, the object (and the code which supports it) must continue to exist. +The low-level functions for manipulating a kobject's reference counts are: + struct kobject *kobject_get(struct kobject *kobj); + void kobject_put(struct kobject *kobj); -struct kset { - struct kobj_type * ktype; - struct list_head list; - struct kobject kobj; - struct kset_uevent_ops * uevent_ops; -}; +A successful call to kobject_get() will increment the kobject's reference +counter and return the pointer to the kobject. +When a reference is released, the call to kobject_put() will decrement the +reference count and, possibly, free the object. Note that kobject_init() +sets the reference count to one, so the code which sets up the kobject will +need to do a kobject_put() eventually to release that reference. -void kset_init(struct kset * k); -int kset_add(struct kset * k); -int kset_register(struct kset * k); -void kset_unregister(struct kset * k); +Because kobjects are dynamic, they must not be declared statically or on +the stack, but instead, always allocated dynamically. Future versions of +the kernel will contain a run-time check for kobjects that are created +statically and will warn the developer of this improper usage. -struct kset * kset_get(struct kset * k); -void kset_put(struct kset * k); +If all that you want to use a kobject for is to provide a reference counter +for your structure, please use the struct kref instead; a kobject would be +overkill. For more information on how to use struct kref, please see the +file Documentation/kref.txt in the Linux kernel source tree. -struct kobject * kset_find_obj(struct kset *, char *); +Creating "simple" kobjects -The type that the kobjects are embedded in is described by the ktype -pointer. +Sometimes all that a developer wants is a way to create a simple directory +in the sysfs hierarchy, and not have to mess with the whole complication of +ksets, show and store functions, and other details. This is the one +exception where a single kobject should be created. To create such an +entry, use the function: -A kset contains a kobject itself, meaning that it may be registered in -the kobject hierarchy and exported via sysfs. More importantly, the -kset may be embedded in a larger data type, and may be part of another -kset (of that object type). + struct kobject *kobject_create_and_add(char *name, struct kobject *parent); -For example, a block device is an object (struct gendisk) that is -contained in a set of block devices. It may also contain a set of -partitions (struct hd_struct) that have been found on the device. The -following code snippet illustrates how to express this properly. +This function will create a kobject and place it in sysfs in the location +underneath the specified parent kobject. To create simple attributes +associated with this kobject, use: - struct gendisk * disk; - ... - disk->kset.kobj.kset = &block_kset; - disk->kset.ktype = &partition_ktype; - kset_register(&disk->kset); + int sysfs_create_file(struct kobject *kobj, struct attribute *attr); +or + int sysfs_create_group(struct kobject *kobj, struct attribute_group *grp); -- The kset that the disk's embedded object belongs to is the - block_kset, and is pointed to by disk->kset.kobj.kset. +Both types of attributes used here, with a kobject that has been created +with the kobject_create_and_add(), can be of type kobj_attribute, so no +special custom attribute is needed to be created. -- The type of objects on the disk's _subordinate_ list are partitions, - and is set in disk->kset.ktype. +See the example module, samples/kobject/kobject-example.c for an +implementation of a simple kobject and attributes. -- The kset is then registered, which handles initializing and adding - the embedded kobject to the hierarchy. -2.2 kset Programming Interface +ktypes and release methods -All kset functions, except kset_find_obj(), eventually forward the -calls to their embedded kobjects after performing kset-specific -operations. ksets offer a similar programming model to kobjects: they -may be used after they are initialized, without registering them in -the hierarchy. +One important thing still missing from the discussion is what happens to a +kobject when its reference count reaches zero. The code which created the +kobject generally does not know when that will happen; if it did, there +would be little point in using a kobject in the first place. Even +predictable object lifecycles become more complicated when sysfs is brought +in as other portions of the kernel can get a reference on any kobject that +is registered in the system. -kset_find_obj() may be used to locate a kobject with a particular -name. The kobject, if found, is returned. +The end result is that a structure protected by a kobject cannot be freed +before its reference count goes to zero. The reference count is not under +the direct control of the code which created the kobject. So that code must +be notified asynchronously whenever the last reference to one of its +kobjects goes away. -There are also some helper functions which names point to the formerly -existing "struct subsystem", whose functions have been taken over by -ksets. +Once you registered your kobject via kobject_add(), you must never use +kfree() to free it directly. The only safe way is to use kobject_put(). It +is good practice to always use kobject_put() after kobject_init() to avoid +errors creeping in. +This notification is done through a kobject's release() method. Usually +such a method has a form like: -decl_subsys(name,type,uevent_ops) + void my_object_release(struct kobject *kobj) + { + struct my_object *mine = container_of(kobj, struct my_object, kobj); -Declares a kset named '<name>_subsys' of type <type> with -uevent_ops <uevent_ops>. For example, + /* Perform any additional cleanup on this object, then... */ + kfree(mine); + } -decl_subsys(devices, &ktype_device, &device_uevent_ops); +One important point cannot be overstated: every kobject must have a +release() method, and the kobject must persist (in a consistent state) +until that method is called. If these constraints are not met, the code is +flawed. Note that the kernel will warn you if you forget to provide a +release() method. Do not try to get rid of this warning by providing an +"empty" release function; you will be mocked mercilessly by the kobject +maintainer if you attempt this. -is equivalent to doing: +Note, the name of the kobject is available in the release function, but it +must NOT be changed within this callback. Otherwise there will be a memory +leak in the kobject core, which makes people unhappy. -struct kset devices_subsys = { - .ktype = &ktype_devices, - .uevent_ops = &device_uevent_ops, -}; -kobject_set_name(&devices_subsys, name); +Interestingly, the release() method is not stored in the kobject itself; +instead, it is associated with the ktype. So let us introduce struct +kobj_type: + + struct kobj_type { + void (*release)(struct kobject *); + struct sysfs_ops *sysfs_ops; + struct attribute **default_attrs; + }; -The objects that are registered with a subsystem that use the -subsystem's default list must have their kset ptr set properly. These -objects may have embedded kobjects or ksets. The -following helper makes setting the kset easier: +This structure is used to describe a particular type of kobject (or, more +correctly, of containing object). Every kobject needs to have an associated +kobj_type structure; a pointer to that structure must be specified when you +call kobject_init() or kobject_init_and_add(). +The release field in struct kobj_type is, of course, a pointer to the +release() method for this type of kobject. The other two fields (sysfs_ops +and default_attrs) control how objects of this type are represented in +sysfs; they are beyond the scope of this document. -kobj_set_kset_s(obj,subsys) +The default_attrs pointer is a list of default attributes that will be +automatically created for any kobject that is registered with this ktype. -- Assumes that obj->kobj exists, and is a struct kobject. -- Sets the kset of that kobject to the kset <subsys>. -int subsystem_register(struct kset *s); -void subsystem_unregister(struct kset *s); +ksets -These are just wrappers around the respective kset_* functions. +A kset is merely a collection of kobjects that want to be associated with +each other. There is no restriction that they be of the same ktype, but be +very careful if they are not. -2.3 sysfs +A kset serves these functions: -ksets are represented in sysfs when their embedded kobjects are -registered. They follow the same rules of parenting, with one -exception. If a kset does not have a parent, nor is its embedded -kobject part of another kset, the kset's parent becomes its dominant -subsystem. + - It serves as a bag containing a group of objects. A kset can be used by + the kernel to track "all block devices" or "all PCI device drivers." -If the kset does not have a parent, its directory is created at the -sysfs root. This should only happen when the kset registered is -embedded in a subsystem itself. + - A kset is also a subdirectory in sysfs, where the associated kobjects + with the kset can show up. Every kset contains a kobject which can be + set up to be the parent of other kobjects; the top-level directories of + the sysfs hierarchy are constructed in this way. + - Ksets can support the "hotplugging" of kobjects and influence how + uevent events are reported to user space. -3. struct ktype +In object-oriented terms, "kset" is the top-level container class; ksets +contain their own kobject, but that kobject is managed by the kset code and +should not be manipulated by any other user. -3.1. Description +A kset keeps its children in a standard kernel linked list. Kobjects point +back to their containing kset via their kset field. In almost all cases, +the kobjects belonging to a ket have that kset (or, strictly, its embedded +kobject) in their parent. -struct kobj_type { - void (*release)(struct kobject *); - struct sysfs_ops * sysfs_ops; - struct attribute ** default_attrs; +As a kset contains a kobject within it, it should always be dynamically +created and never declared statically or on the stack. To create a new +kset use: + struct kset *kset_create_and_add(const char *name, + struct kset_uevent_ops *u, + struct kobject *parent); + +When you are finished with the kset, call: + void kset_unregister(struct kset *kset); +to destroy it. + +An example of using a kset can be seen in the +samples/kobject/kset-example.c file in the kernel tree. + +If a kset wishes to control the uevent operations of the kobjects +associated with it, it can use the struct kset_uevent_ops to handle it: + +struct kset_uevent_ops { + int (*filter)(struct kset *kset, struct kobject *kobj); + const char *(*name)(struct kset *kset, struct kobject *kobj); + int (*uevent)(struct kset *kset, struct kobject *kobj, + struct kobj_uevent_env *env); }; -Object types require specific functions for converting between the -generic object and the more complex type. struct kobj_type provides -the object-specific fields, which include: +The filter function allows a kset to prevent a uevent from being emitted to +userspace for a specific kobject. If the function returns 0, the uevent +will not be emitted. + +The name function will be called to override the default name of the kset +that the uevent sends to userspace. By default, the name will be the same +as the kset itself, but this function, if present, can override that name. + +The uevent function will be called when the uevent is about to be sent to +userspace to allow more environment variables to be added to the uevent. + +One might ask how, exactly, a kobject is added to a kset, given that no +functions which perform that function have been presented. The answer is +that this task is handled by kobject_add(). When a kobject is passed to +kobject_add(), its kset member should point to the kset to which the +kobject will belong. kobject_add() will handle the rest. + +If the kobject belonging to a kset has no parent kobject set, it will be +added to the kset's directory. Not all members of a kset do necessarily +live in the kset directory. If an explicit parent kobject is assigned +before the kobject is added, the kobject is registered with the kset, but +added below the parent kobject. + + +Kobject removal -- release: Called when the kobject's reference count reaches 0. This - should convert the object to the more complex type and free it. +After a kobject has been registered with the kobject core successfully, it +must be cleaned up when the code is finished with it. To do that, call +kobject_put(). By doing this, the kobject core will automatically clean up +all of the memory allocated by this kobject. If a KOBJ_ADD uevent has been +sent for the object, a corresponding KOBJ_REMOVE uevent will be sent, and +any other sysfs housekeeping will be handled for the caller properly. -- sysfs_ops: Provides conversion functions for sysfs access. Please - see the sysfs documentation for more information. +If you need to do a two-stage delete of the kobject (say you are not +allowed to sleep when you need to destroy the object), then call +kobject_del() which will unregister the kobject from sysfs. This makes the +kobject "invisible", but it is not cleaned up, and the reference count of +the object is still the same. At a later time call kobject_put() to finish +the cleanup of the memory associated with the kobject. -- default_attrs: Default attributes to be exported via sysfs when the - object is registered.Note that the last attribute has to be - initialized to NULL ! You can find a complete implementation - in block/genhd.c +kobject_del() can be used to drop the reference to the parent object, if +circular references are constructed. It is valid in some cases, that a +parent objects references a child. Circular references _must_ be broken +with an explicit call to kobject_del(), so that a release functions will be +called, and the objects in the former circle release each other. -Instances of struct kobj_type are not registered; only referenced by -the kset. A kobj_type may be referenced by an arbitrary number of -ksets, as there may be disparate sets of identical objects. +Example code to copy from +For a more complete example of using ksets and kobjects properly, see the +sample/kobject/kset-example.c code. diff --git a/Documentation/lguest/lguest.c b/Documentation/lguest/lguest.c index 42008395534..9b0e322118b 100644 --- a/Documentation/lguest/lguest.c +++ b/Documentation/lguest/lguest.c @@ -1040,6 +1040,11 @@ static void add_virtqueue(struct device *dev, unsigned int num_descs, / getpagesize(); p = get_pages(pages); + /* Initialize the virtqueue */ + vq->next = NULL; + vq->last_avail_idx = 0; + vq->dev = dev; + /* Initialize the configuration. */ vq->config.num = num_descs; vq->config.irq = devices.next_irq++; @@ -1057,9 +1062,6 @@ static void add_virtqueue(struct device *dev, unsigned int num_descs, for (i = &dev->vq; *i; i = &(*i)->next); *i = vq; - /* Link virtqueue back to device. */ - vq->dev = dev; - /* Set the routine to call when the Guest does something to this * virtqueue. */ vq->handle_output = handle_output; @@ -1093,6 +1095,7 @@ static struct device *new_device(const char *name, u16 type, int fd, dev->desc = new_dev_desc(type); dev->handle_input = handle_input; dev->name = name; + dev->vq = NULL; return dev; } diff --git a/Documentation/lguest/lguest.txt b/Documentation/lguest/lguest.txt index 7885ab2d5f5..722d4e7fbeb 100644 --- a/Documentation/lguest/lguest.txt +++ b/Documentation/lguest/lguest.txt @@ -109,10 +109,6 @@ Running Lguest: See http://linux-net.osdl.org/index.php/Bridge for general information on how to get bridging working. -- You can also create an inter-guest network using - "--sharenet=<filename>": any two guests using the same file are on - the same network. This file is created if it does not exist. - There is a helpful mailing list at http://ozlabs.org/mailman/listinfo/lguest Good luck! diff --git a/Documentation/local_ops.txt b/Documentation/local_ops.txt index 1a45f11e645..4269a1105b3 100644 --- a/Documentation/local_ops.txt +++ b/Documentation/local_ops.txt @@ -68,29 +68,6 @@ typedef struct { atomic_long_t a; } local_t; variable can be read when reading some _other_ cpu's variables. -* Rules to follow when using local atomic operations - -- Variables touched by local ops must be per cpu variables. -- _Only_ the CPU owner of these variables must write to them. -- This CPU can use local ops from any context (process, irq, softirq, nmi, ...) - to update its local_t variables. -- Preemption (or interrupts) must be disabled when using local ops in - process context to make sure the process won't be migrated to a - different CPU between getting the per-cpu variable and doing the - actual local op. -- When using local ops in interrupt context, no special care must be - taken on a mainline kernel, since they will run on the local CPU with - preemption already disabled. I suggest, however, to explicitly - disable preemption anyway to make sure it will still work correctly on - -rt kernels. -- Reading the local cpu variable will provide the current copy of the - variable. -- Reads of these variables can be done from any CPU, because updates to - "long", aligned, variables are always atomic. Since no memory - synchronization is done by the writer CPU, an outdated copy of the - variable can be read when reading some _other_ cpu's variables. - - * How to use local atomic operations #include <linux/percpu.h> diff --git a/Documentation/namespaces/compatibility-list.txt b/Documentation/namespaces/compatibility-list.txt new file mode 100644 index 00000000000..defc5589bfc --- /dev/null +++ b/Documentation/namespaces/compatibility-list.txt @@ -0,0 +1,39 @@ + Namespaces compatibility list + +This document contains the information about the problems user +may have when creating tasks living in different namespaces. + +Here's the summary. This matrix shows the known problems, that +occur when tasks share some namespace (the columns) while living +in different other namespaces (the rows): + + UTS IPC VFS PID User Net +UTS X +IPC X 1 +VFS X +PID 1 1 X +User 2 2 X +Net X + +1. Both the IPC and the PID namespaces provide IDs to address + object inside the kernel. E.g. semaphore with IPCID or + process group with pid. + + In both cases, tasks shouldn't try exposing this ID to some + other task living in a different namespace via a shared filesystem + or IPC shmem/message. The fact is that this ID is only valid + within the namespace it was obtained in and may refer to some + other object in another namespace. + +2. Intentionally, two equal user IDs in different user namespaces + should not be equal from the VFS point of view. In other + words, user 10 in one user namespace shouldn't have the same + access permissions to files, belonging to user 10 in another + namespace. + + The same is true for the IPC namespaces being shared - two users + from different user namespaces should not access the same IPC objects + even having equal UIDs. + + But currently this is not so. + diff --git a/Documentation/networking/bonding.txt b/Documentation/networking/bonding.txt index 11340625e36..6cc30e0d579 100644 --- a/Documentation/networking/bonding.txt +++ b/Documentation/networking/bonding.txt @@ -554,6 +554,30 @@ xmit_hash_policy This algorithm is 802.3ad compliant. + layer2+3 + + This policy uses a combination of layer2 and layer3 + protocol information to generate the hash. + + Uses XOR of hardware MAC addresses and IP addresses to + generate the hash. The formula is + + (((source IP XOR dest IP) AND 0xffff) XOR + ( source MAC XOR destination MAC )) + modulo slave count + + This algorithm will place all traffic to a particular + network peer on the same slave. For non-IP traffic, + the formula is the same as for the layer2 transmit + hash policy. + + This policy is intended to provide a more balanced + distribution of traffic than layer2 alone, especially + in environments where a layer3 gateway device is + required to reach most destinations. + + This algorithm is 802.3ad complient. + layer3+4 This policy uses upper layer protocol information, @@ -589,8 +613,9 @@ xmit_hash_policy or may not tolerate this noncompliance. The default value is layer2. This option was added in bonding -version 2.6.3. In earlier versions of bonding, this parameter does -not exist, and the layer2 policy is the only policy. + version 2.6.3. In earlier versions of bonding, this parameter + does not exist, and the layer2 policy is the only policy. The + layer2+3 value was added for bonding version 3.2.2. 3. Configuring Bonding Devices diff --git a/Documentation/networking/driver.txt b/Documentation/networking/driver.txt index 4f7da5a2bf4..ea72d2e66ca 100644 --- a/Documentation/networking/driver.txt +++ b/Documentation/networking/driver.txt @@ -61,7 +61,10 @@ Transmit path guidelines: 2) Do not forget to update netdev->trans_start to jiffies after each new tx packet is given to the hardware. -3) Do not forget that once you return 0 from your hard_start_xmit +3) A hard_start_xmit method must not modify the shared parts of a + cloned SKB. + +4) Do not forget that once you return 0 from your hard_start_xmit method, it is your driver's responsibility to free up the SKB and in some finite amount of time. diff --git a/Documentation/networking/wavelan.txt b/Documentation/networking/wavelan.txt index c1acf5eb371..afa6e521c68 100644 --- a/Documentation/networking/wavelan.txt +++ b/Documentation/networking/wavelan.txt @@ -12,8 +12,8 @@ and many Linux driver to support it. "wavelan" driver (old ISA Wavelan) ---------------- o Config : Network device -> Wireless LAN -> AT&T WaveLAN - o Location : .../drivers/net/wavelan* - o in-line doc : .../drivers/net/wavelan.p.h + o Location : .../drivers/net/wireless/wavelan* + o in-line doc : .../drivers/net/wireless/wavelan.p.h o on-line doc : http://www.hpl.hp.com/personal/Jean_Tourrilhes/Linux/Wavelan.html diff --git a/Documentation/nfsroot.txt b/Documentation/nfsroot.txt index 16a7cae2721..31b32917234 100644 --- a/Documentation/nfsroot.txt +++ b/Documentation/nfsroot.txt @@ -92,8 +92,10 @@ ip=<client-ip>:<server-ip>:<gw-ip>:<netmask>:<hostname>:<device>:<autoconf> autoconfiguration. The <autoconf> parameter can appear alone as the value to the `ip' - parameter (without all the ':' characters before) in which case auto- - configuration is used. + parameter (without all the ':' characters before). If the value is + "ip=off" or "ip=none", no autoconfiguration will take place, otherwise + autoconfiguration will take place. The most common way to use this + is "ip=dhcp". <client-ip> IP address of the client. @@ -142,8 +144,10 @@ ip=<client-ip>:<server-ip>:<gw-ip>:<netmask>:<hostname>:<device>:<autoconf> into the kernel will be used, regardless of the value of this option. - off or none: don't use autoconfiguration (default) + off or none: don't use autoconfiguration + (do static IP assignment instead) on or any: use any protocol available in the kernel + (default) dhcp: use DHCP bootp: use BOOTP rarp: use RARP diff --git a/Documentation/parport-lowlevel.txt b/Documentation/parport-lowlevel.txt index 265fcdcb8e5..120eb20dbb0 100644 --- a/Documentation/parport-lowlevel.txt +++ b/Documentation/parport-lowlevel.txt @@ -339,6 +339,10 @@ Use this function to register your device driver on a parallel port ('port'). Once you have done that, you will be able to use parport_claim and parport_release in order to use the port. +The ('name') argument is the name of the device that appears in /proc +filesystem. The string must be valid for the whole lifetime of the +device (until parport_unregister_device is called). + This function will register three callbacks into your driver: 'preempt', 'wakeup' and 'irq'. Each of these may be NULL in order to indicate that you do not want a callback. diff --git a/Documentation/pnp.txt b/Documentation/pnp.txt index 481faf515d5..a327db67782 100644 --- a/Documentation/pnp.txt +++ b/Documentation/pnp.txt @@ -17,9 +17,9 @@ The User Interface ------------------ The Linux Plug and Play user interface provides a means to activate PnP devices for legacy and user level drivers that do not support Linux Plug and Play. The -user interface is integrated into driverfs. +user interface is integrated into sysfs. -In addition to the standard driverfs file the following are created in each +In addition to the standard sysfs file the following are created in each device's directory: id - displays a list of support EISA IDs options - displays possible resource configurations diff --git a/Documentation/powerpc/booting-without-of.txt b/Documentation/powerpc/booting-without-of.txt index ac1be25c1e2..e9a3cb1d6b0 100644 --- a/Documentation/powerpc/booting-without-of.txt +++ b/Documentation/powerpc/booting-without-of.txt @@ -1645,8 +1645,9 @@ platforms are moved over to use the flattened-device-tree model. MAC addresses passed by the firmware when no information other than indices is available to associate an address with a device. - phy-connection-type : a string naming the controller/PHY interface type, - i.e., "mii" (default), "rmii", "gmii", "rgmii", "rgmii-id", "tbi", - or "rtbi". + i.e., "mii" (default), "rmii", "gmii", "rgmii", "rgmii-id" (Internal + Delay), "rgmii-txid" (delay on TX only), "rgmii-rxid" (delay on RX only), + "tbi", or "rtbi". Example: ucc@2000 { diff --git a/Documentation/s390/cds.txt b/Documentation/s390/cds.txt index 3081927cc2d..c4b7b2bd369 100644 --- a/Documentation/s390/cds.txt +++ b/Documentation/s390/cds.txt @@ -133,7 +133,7 @@ During its startup the Linux/390 system checks for peripheral devices. Each of those devices is uniquely defined by a so called subchannel by the ESA/390 channel subsystem. While the subchannel numbers are system generated, each subchannel also takes a user defined attribute, the so called device number. -Both subchannel number and device number cannot exceed 65535. During driverfs +Both subchannel number and device number cannot exceed 65535. During sysfs initialisation, the information about control unit type and device types that imply specific I/O commands (channel command words - CCWs) in order to operate the device are gathered. Device drivers can retrieve this set of hardware diff --git a/Documentation/sysctl/vm.txt b/Documentation/sysctl/vm.txt index b89570c3043..6f31f0a247d 100644 --- a/Documentation/sysctl/vm.txt +++ b/Documentation/sysctl/vm.txt @@ -34,6 +34,8 @@ Currently, these files are in /proc/sys/vm: - oom_kill_allocating_task - mmap_min_address - numa_zonelist_order +- nr_hugepages +- nr_overcommit_hugepages ============================================================== @@ -305,3 +307,20 @@ will select "node" order in following case. Otherwise, "zone" order will be selected. Default order is recommended unless this is causing problems for your system/application. + +============================================================== + +nr_hugepages + +Change the minimum size of the hugepage pool. + +See Documentation/vm/hugetlbpage.txt + +============================================================== + +nr_overcommit_hugepages + +Change the maximum size of the hugepage pool. The maximum is +nr_hugepages + nr_overcommit_hugepages. + +See Documentation/vm/hugetlbpage.txt diff --git a/Documentation/thinkpad-acpi.txt b/Documentation/thinkpad-acpi.txt index ec499265dec..10c041ca13c 100644 --- a/Documentation/thinkpad-acpi.txt +++ b/Documentation/thinkpad-acpi.txt @@ -1,7 +1,7 @@ ThinkPad ACPI Extras Driver - Version 0.16 - August 2nd, 2007 + Version 0.17 + October 04th, 2007 Borislav Deianov <borislav@users.sf.net> Henrique de Moraes Holschuh <hmh@hmh.eng.br> @@ -923,19 +923,34 @@ sysfs backlight device "thinkpad_screen" This feature allows software control of the LCD brightness on ThinkPad models which don't have a hardware brightness slider. -It has some limitations: the LCD backlight cannot be actually turned on or off -by this interface, and in many ThinkPad models, the "dim while on battery" -functionality will be enabled by the BIOS when this interface is used, and -cannot be controlled. - -The backlight control has eight levels, ranging from 0 to 7. Some of the -levels may not be distinct. - -There are two interfaces to the firmware for brightness control, EC and CMOS. -To select which one should be used, use the brightness_mode module parameter: -brightness_mode=1 selects EC mode, brightness_mode=2 selects CMOS mode, -brightness_mode=3 selects both EC and CMOS. The driver tries to autodetect -which interface to use. +It has some limitations: the LCD backlight cannot be actually turned on or +off by this interface, and in many ThinkPad models, the "dim while on +battery" functionality will be enabled by the BIOS when this interface is +used, and cannot be controlled. + +On IBM (and some of the earlier Lenovo) ThinkPads, the backlight control +has eight brightness levels, ranging from 0 to 7. Some of the levels +may not be distinct. Later Lenovo models that implement the ACPI +display backlight brightness control methods have 16 levels, ranging +from 0 to 15. + +There are two interfaces to the firmware for direct brightness control, +EC and CMOS. To select which one should be used, use the +brightness_mode module parameter: brightness_mode=1 selects EC mode, +brightness_mode=2 selects CMOS mode, brightness_mode=3 selects both EC +and CMOS. The driver tries to autodetect which interface to use. + +When display backlight brightness controls are available through the +standard ACPI interface, it is best to use it instead of this direct +ThinkPad-specific interface. The driver will disable its native +backlight brightness control interface if it detects that the standard +ACPI interface is available in the ThinkPad. + +The brightness_enable module parameter can be used to control whether +the LCD brightness control feature will be enabled when available. +brightness_enable=0 forces it to be disabled. brightness_enable=1 +forces it to be enabled when available, even if the standard ACPI +interface is also available. Procfs notes: @@ -947,11 +962,11 @@ Procfs notes: Sysfs notes: -The interface is implemented through the backlight sysfs class, which is poorly -documented at this time. +The interface is implemented through the backlight sysfs class, which is +poorly documented at this time. -Locate the thinkpad_screen device under /sys/class/backlight, and inside it -there will be the following attributes: +Locate the thinkpad_screen device under /sys/class/backlight, and inside +it there will be the following attributes: max_brightness: Reads the maximum brightness the hardware can be set to. @@ -961,17 +976,19 @@ there will be the following attributes: Reads what brightness the screen is set to at this instant. brightness: - Writes request the driver to change brightness to the given - value. Reads will tell you what brightness the driver is trying - to set the display to when "power" is set to zero and the display - has not been dimmed by a kernel power management event. + Writes request the driver to change brightness to the + given value. Reads will tell you what brightness the + driver is trying to set the display to when "power" is set + to zero and the display has not been dimmed by a kernel + power management event. power: - power management mode, where 0 is "display on", and 1 to 3 will - dim the display backlight to brightness level 0 because - thinkpad-acpi cannot really turn the backlight off. Kernel - power management events can temporarily increase the current - power management level, i.e. they can dim the display. + power management mode, where 0 is "display on", and 1 to 3 + will dim the display backlight to brightness level 0 + because thinkpad-acpi cannot really turn the backlight + off. Kernel power management events can temporarily + increase the current power management level, i.e. they can + dim the display. Volume control -- /proc/acpi/ibm/volume diff --git a/Documentation/tipar.txt b/Documentation/tipar.txt deleted file mode 100644 index 67133baef6e..00000000000 --- a/Documentation/tipar.txt +++ /dev/null @@ -1,93 +0,0 @@ - - Parallel link cable for Texas Instruments handhelds - =================================================== - - -Author: Romain Lievin -Homepage: http://lpg.ticalc.org/prj_tidev/index.html - - -INTRODUCTION: - -This is a driver for the very common home-made parallel link cable, a cable -designed for connecting TI8x/9x graphing calculators (handhelds) to a computer -or workstation (Alpha, Sparc). Given that driver is built on parport, the -parallel port abstraction layer, this driver is architecture-independent. - -It can also be used with another device plugged on the same port (such as a -ZIP drive). I have a 100MB ZIP and both of them work fine! - -If you need more information, please visit the 'TI drivers' homepage at the URL -above. - -WHAT YOU NEED: - -A TI calculator and a program capable of communicating with your calculator. - -TiLP will work for sure (since I am its developer!). yal92 may be able to use -it by changing tidev for tipar (may require some hacking...). - -HOW TO USE IT: - -You must have first compiled parport support (CONFIG_PARPORT_DEV): either -compiled in your kernel, either as a module. - -Next, (as root): - - modprobe parport - modprobe tipar - -If it is not already there (it usually is), create the device: - - mknod /dev/tipar0 c 115 0 - mknod /dev/tipar1 c 115 1 - mknod /dev/tipar2 c 115 2 - -You will have to set permissions on this device to allow you to read/write -from it: - - chmod 666 /dev/tipar[0..2] - -Now you are ready to run a linking program such as TiLP. Be sure to configure -it properly (RTFM). - -MODULE PARAMETERS: - - You can set these with: modprobe tipar NAME=VALUE - There is currently no way to set these on a per-cable basis. - - NAME: timeout - TYPE: integer - DEFAULT: 15 - DESC: Timeout value in tenth of seconds. If no data is available once this - time has expired then the driver will return with a timeout error. - - NAME: delay - TYPE: integer - DEFAULT: 10 - DESC: Inter-bit delay in micro-seconds. A lower value gives an higher data - rate but makes transmission less reliable. - -These parameters can be changed at run time by any program via ioctl(2) calls -as listed in ./include/linux/ticable.h. - -Rather than write 50 pages describing the ioctl() and so on, it is -perhaps more useful you look at ticables library (dev_link.c) that demonstrates -how to use them, and demonstrates the features of the driver. This is -probably a lot more useful to people interested in writing applications -that will be using this driver. - -QUIRKS/BUGS: - -None. - -HOW TO CONTACT US: - -You can email me at roms@lpg.ticalc.org. Please prefix the subject line -with "TIPAR: " so that I am certain to notice your message. -You can also mail JB at jb@jblache.org. He packaged these drivers for Debian. - -CREDITS: - -The code is based on tidev.c & parport.c. -The driver has been developed independently of Texas Instruments. diff --git a/Documentation/tty.txt b/Documentation/tty.txt index 048a8762cfb..8e65c4498c5 100644 --- a/Documentation/tty.txt +++ b/Documentation/tty.txt @@ -132,6 +132,14 @@ set_termios() Notify the tty driver that the device's termios tty->termios. Previous settings should be passed in the "old" argument. + The API is defined such that the driver should return + the actual modes selected. This means that the + driver function is responsible for modifying any + bits in the request it cannot fulfill to indicate + the actual modes being used. A device with no + hardware capability for change (eg a USB dongle or + virtual port) can provide NULL for this method. + throttle() Notify the tty driver that input buffers for the line discipline are close to full, and it should somehow signal that no more characters should be diff --git a/Documentation/usb/power-management.txt b/Documentation/usb/power-management.txt index 97842deec47..b2fc4d4a991 100644 --- a/Documentation/usb/power-management.txt +++ b/Documentation/usb/power-management.txt @@ -278,6 +278,14 @@ optional. The methods' jobs are quite simple: (although the interfaces will be in the same altsettings as before the suspend). +If the device is disconnected or powered down while it is suspended, +the disconnect method will be called instead of the resume or +reset_resume method. This is also quite likely to happen when +waking up from hibernation, as many systems do not maintain suspend +current to the USB host controllers during hibernation. (It's +possible to work around the hibernation-forces-disconnect problem by +using the USB Persist facility.) + The reset_resume method is used by the USB Persist facility (see Documentation/usb/persist.txt) and it can also be used under certain circumstances when CONFIG_USB_PERSIST is not enabled. Currently, if a diff --git a/Documentation/vm/hugetlbpage.txt b/Documentation/vm/hugetlbpage.txt index 51ccc48aa76..f962d01bea2 100644 --- a/Documentation/vm/hugetlbpage.txt +++ b/Documentation/vm/hugetlbpage.txt @@ -30,9 +30,10 @@ alignment and size of the arguments to the above system calls. The output of "cat /proc/meminfo" will have lines like: ..... -HugePages_Total: xxx -HugePages_Free: yyy -HugePages_Rsvd: www +HugePages_Total: vvv +HugePages_Free: www +HugePages_Rsvd: xxx +HugePages_Surp: yyy Hugepagesize: zzz kB where: @@ -42,6 +43,10 @@ allocated. HugePages_Rsvd is short for "reserved," and is the number of hugepages for which a commitment to allocate from the pool has been made, but no allocation has yet been made. It's vaguely analogous to overcommit. +HugePages_Surp is short for "surplus," and is the number of hugepages in +the pool above the value in /proc/sys/vm/nr_hugepages. The maximum +number of surplus hugepages is controlled by +/proc/sys/vm/nr_overcommit_hugepages. /proc/filesystems should also show a filesystem of type "hugetlbfs" configured in the kernel. @@ -71,7 +76,25 @@ or failure of allocation depends on the amount of physically contiguous memory that is preset in system at this time. System administrators may want to put this command in one of the local rc init files. This will enable the kernel to request huge pages early in the boot process (when the possibility -of getting physical contiguous pages is still very high). +of getting physical contiguous pages is still very high). In either +case, adminstrators will want to verify the number of hugepages actually +allocated by checking the sysctl or meminfo. + +/proc/sys/vm/nr_overcommit_hugepages indicates how large the pool of +hugepages can grow, if more hugepages than /proc/sys/vm/nr_hugepages are +requested by applications. echo'ing any non-zero value into this file +indicates that the hugetlb subsystem is allowed to try to obtain +hugepages from the buddy allocator, if the normal pool is exhausted. As +these surplus hugepages go out of use, they are freed back to the buddy +allocator. + +Caveat: Shrinking the pool via nr_hugepages while a surplus is in effect +will allow the number of surplus huge pages to exceed the overcommit +value, as the pool hugepages (which must have been in use for a surplus +hugepages to be allocated) will become surplus hugepages. As long as +this condition holds, however, no more surplus huge pages will be +allowed on the system until one of the two sysctls are increased +sufficiently, or the surplus huge pages go out of use and are freed. If the user applications are going to request hugepages using mmap system call, then it is required that system administrator mount a file system of @@ -94,8 +117,8 @@ provided on command line then no limits are set. For size and nr_inodes options, you can use [G|g]/[M|m]/[K|k] to represent giga/mega/kilo. For example, size=2K has the same meaning as size=2048. -read and write system calls are not supported on files that reside on hugetlb -file systems. +While read system calls are supported on files that reside on hugetlb +file systems, write system calls are not. Regular chown, chgrp, and chmod commands (with right permissions) could be used to change the file attributes on hugetlbfs. diff --git a/Documentation/vm/slabinfo.c b/Documentation/vm/slabinfo.c index 7047696c47a..488c1f31b99 100644 --- a/Documentation/vm/slabinfo.c +++ b/Documentation/vm/slabinfo.c @@ -1021,7 +1021,7 @@ void read_slab_dir(void) char *t; int count; - if (chdir("/sys/slab")) + if (chdir("/sys/kernel/slab")) fatal("SYSFS support for SLUB not active\n"); dir = opendir("."); diff --git a/Documentation/vm/slub.txt b/Documentation/vm/slub.txt index d17f324db9f..dcf8bcf846d 100644 --- a/Documentation/vm/slub.txt +++ b/Documentation/vm/slub.txt @@ -63,7 +63,7 @@ In case you forgot to enable debugging on the kernel command line: It is possible to enable debugging manually when the kernel is up. Look at the contents of: -/sys/slab/<slab name>/ +/sys/kernel/slab/<slab name>/ Look at the writable files. Writing 1 to them will enable the corresponding debug option. All options can be set on a slab that does diff --git a/Documentation/watchdog/watchdog-api.txt b/Documentation/watchdog/watchdog-api.txt index bb7cb1d31ec..4cc4ba9d715 100644 --- a/Documentation/watchdog/watchdog-api.txt +++ b/Documentation/watchdog/watchdog-api.txt @@ -42,23 +42,27 @@ like this source file: see Documentation/watchdog/src/watchdog-simple.c A more advanced driver could for example check that a HTTP server is still responding before doing the write call to ping the watchdog. -When the device is closed, the watchdog is disabled. This is not -always such a good idea, since if there is a bug in the watchdog -daemon and it crashes the system will not reboot. Because of this, -some of the drivers support the configuration option "Disable watchdog -shutdown on close", CONFIG_WATCHDOG_NOWAYOUT. If it is set to Y when -compiling the kernel, there is no way of disabling the watchdog once -it has been started. So, if the watchdog daemon crashes, the system -will reboot after the timeout has passed. Watchdog devices also usually -support the nowayout module parameter so that this option can be controlled -at runtime. - -Drivers will not disable the watchdog, unless a specific magic character 'V' -has been sent /dev/watchdog just before closing the file. If the userspace -daemon closes the file without sending this special character, the driver -will assume that the daemon (and userspace in general) died, and will stop -pinging the watchdog without disabling it first. This will then cause a -reboot if the watchdog is not re-opened in sufficient time. +When the device is closed, the watchdog is disabled, unless the "Magic +Close" feature is supported (see below). This is not always such a +good idea, since if there is a bug in the watchdog daemon and it +crashes the system will not reboot. Because of this, some of the +drivers support the configuration option "Disable watchdog shutdown on +close", CONFIG_WATCHDOG_NOWAYOUT. If it is set to Y when compiling +the kernel, there is no way of disabling the watchdog once it has been +started. So, if the watchdog daemon crashes, the system will reboot +after the timeout has passed. Watchdog devices also usually support +the nowayout module parameter so that this option can be controlled at +runtime. + +Magic Close feature: + +If a driver supports "Magic Close", the driver will not disable the +watchdog unless a specific magic character 'V' has been sent to +/dev/watchdog just before closing the file. If the userspace daemon +closes the file without sending this special character, the driver +will assume that the daemon (and userspace in general) died, and will +stop pinging the watchdog without disabling it first. This will then +cause a reboot if the watchdog is not re-opened in sufficient time. The ioctl API: diff --git a/Documentation/x86_64/uefi.txt b/Documentation/x86_64/uefi.txt new file mode 100644 index 00000000000..91a98edfb58 --- /dev/null +++ b/Documentation/x86_64/uefi.txt @@ -0,0 +1,29 @@ +General note on [U]EFI x86_64 support +------------------------------------- + +The nomenclature EFI and UEFI are used interchangeably in this document. + +Although the tools below are _not_ needed for building the kernel, +the needed bootloader support and associated tools for x86_64 platforms +with EFI firmware and specifications are listed below. + +1. UEFI specification: http://www.uefi.org + +2. Booting Linux kernel on UEFI x86_64 platform requires bootloader + support. Elilo with x86_64 support can be used. + +3. x86_64 platform with EFI/UEFI firmware. + +Mechanics: +--------- +- Build the kernel with the following configuration. + CONFIG_FB_EFI=y + CONFIG_FRAMEBUFFER_CONSOLE=y +- Create a VFAT partition on the disk +- Copy the following to the VFAT partition: + elilo bootloader with x86_64 support, elilo configuration file, + kernel image built in first step and corresponding + initrd. Instructions on building elilo and its dependencies + can be found in the elilo sourceforge project. +- Boot to EFI shell and invoke elilo choosing the kernel image built + in first step. diff --git a/Documentation/zh_CN/CodingStyle b/Documentation/zh_CN/CodingStyle new file mode 100644 index 00000000000..ecd9307a641 --- /dev/null +++ b/Documentation/zh_CN/CodingStyle @@ -0,0 +1,701 @@ +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: Zhang Le <r0bertz@gentoo.org> +--------------------------------------------------------------------- +Documentation/CodingStyle的中文翻译 + +如果想评论或更新本文的内容，请直接发信到LKML。如果你使用英文交流有困难的话，也可 +以向中文版维护者求助。如果本翻译更新不及时或者翻译存在问题，请联系中文版维护者。 + +中文版维护者： 张乐 Zhang Le <r0bertz@gentoo.org> +中文版翻译者： 张乐 Zhang Le <r0bertz@gentoo.org> +中文版校译者： 王聪 Wang Cong <xiyou.wangcong@gmail.com> + wheelz <kernel.zeng@gmail.com> + 管旭东 Xudong Guan <xudong.guan@gmail.com> + Li Zefan <lizf@cn.fujitsu.com> + Wang Chen <wangchen@cn.fujitsu.com> +以下为正文 +--------------------------------------------------------------------- + + Linux内核代码风格 + +这是一个简短的文档，描述了linux内核的首选代码风格。代码风格是因人而异的，而且我 +不愿意把我的观点强加给任何人，不过这里所讲述的是我必须要维护的代码所遵守的风格， +并且我也希望绝大多数其他代码也能遵守这个风格。请在写代码时至少考虑一下本文所述的 +风格。 + +首先，我建议你打印一份GNU代码规范，然后不要读它。烧了它，这是一个具有重大象征性 +意义的动作。 + +不管怎样，现在我们开始： + + + 第一章：缩进 + +制表符是8个字符，所以缩进也是8个字符。有些异端运动试图将缩进变为4（乃至2）个字符 +深，这几乎相当于尝试将圆周率的值定义为3。 + +理由：缩进的全部意义就在于清楚的定义一个控制块起止于何处。尤其是当你盯着你的屏幕 +连续看了20小时之后，你将会发现大一点的缩进会使你更容易分辨缩进。 + +现在，有些人会抱怨8个字符的缩进会使代码向右边移动的太远，在80个字符的终端屏幕上 +就很难读这样的代码。这个问题的答案是，如果你需要3级以上的缩进，不管用何种方式你 +的代码已经有问题了，应该修正你的程序。 + +简而言之，8个字符的缩进可以让代码更容易阅读，还有一个好处是当你的函数嵌套太深的 +时候可以给你警告。留心这个警告。 + +在switch语句中消除多级缩进的首选的方式是让“switch”和从属于它的“case”标签对齐于同 +一列，而不要“两次缩进”“case”标签。比如： + + switch (suffix) { + case 'G': + case 'g': + mem <<= 30; + break; + case 'M': + case 'm': + mem <<= 20; + break; + case 'K': + case 'k': + mem <<= 10; + /* fall through */ + default: + break; + } + + +不要把多个语句放在一行里，除非你有什么东西要隐藏： + + if (condition) do_this; + do_something_everytime; + +也不要在一行里放多个赋值语句。内核代码风格超级简单。就是避免可能导致别人误读的表 +达式。 + +除了注释、文档和Kconfig之外，不要使用空格来缩进，前面的例子是例外，是有意为之。 + +选用一个好的编辑器，不要在行尾留空格。 + + + 第二章：把长的行和字符串打散 + +代码风格的意义就在于使用平常使用的工具来维持代码的可读性和可维护性。 + +每一行的长度的限制是80列，我们强烈建议您遵守这个惯例。 + +长于80列的语句要打散成有意义的片段。每个片段要明显短于原来的语句，而且放置的位置 +也明显的靠右。同样的规则也适用于有很长参数列表的函数头。长字符串也要打散成较短的 +字符串。唯一的例外是超过80列可以大幅度提高可读性并且不会隐藏信息的情况。 + +void fun(int a, int b, int c) +{ + if (condition) + printk(KERN_WARNING "Warning this is a long printk with " + "3 parameters a: %u b: %u " + "c: %u \n", a, b, c); + else + next_statement; +} + + 第三章：大括号和空格的放置 + +C语言风格中另外一个常见问题是大括号的放置。和缩进大小不同，选择或弃用某种放置策 +略并没有多少技术上的原因，不过首选的方式，就像Kernighan和Ritchie展示给我们的，是 +把起始大括号放在行尾，而把结束大括号放在行首，所以： + + if (x is true) { + we do y + } + +这适用于所有的非函数语句块（if、switch、for、while、do）。比如： + + switch (action) { + case KOBJ_ADD: + return "add"; + case KOBJ_REMOVE: + return "remove"; + case KOBJ_CHANGE: + return "change"; + default: + return NULL; + } + +不过，有一个例外，那就是函数：函数的起始大括号放置于下一行的开头，所以： + + int function(int x) + { + body of function + } + +全世界的异端可能会抱怨这个不一致性是……呃……不一致的，不过所有思维健全的人都知道（ +a）K&R是_正确的_，并且（b）K&R是正确的。此外，不管怎样函数都是特殊的（在C语言中 +，函数是不能嵌套的）。 + +注意结束大括号独自占据一行，除非它后面跟着同一个语句的剩余部分，也就是do语句中的 +“while”或者if语句中的“else”，像这样： + + do { + body of do-loop + } while (condition); + +和 + + if (x == y) { + .. + } else if (x > y) { + ... + } else { + .... + } + +理由：K&R。 + +也请注意这种大括号的放置方式也能使空（或者差不多空的）行的数量最小化，同时不失可 +读性。因此，由于你的屏幕上的新行是不可再生资源（想想25行的终端屏幕），你将会有更 +多的空行来放置注释。 + +当只有一个单独的语句的时候，不用加不必要的大括号。 + +if (condition) + action(); + +这点不适用于本身为某个条件语句的一个分支的单独语句。这时需要在两个分支里都使用大 +括号。 + +if (condition) { + do_this(); + do_that(); +} else { + otherwise(); +} + + 3.1：空格 + +Linux内核的空格使用方式（主要）取决于它是用于函数还是关键字。（大多数）关键字后 +要加一个空格。值得注意的例外是sizeof、typeof、alignof和__attribute__，这些关键字 +某些程度上看起来更像函数（它们在Linux里也常常伴随小括号而使用，尽管在C语言里这样 +的小括号不是必需的，就像“struct fileinfo info”声明过后的“sizeof info”）。 + +所以在这些关键字之后放一个空格： + if, switch, case, for, do, while +但是不要在sizeof、typeof、alignof或者__attribute__这些关键字之后放空格。例如， + s = sizeof(struct file); + +不要在小括号里的表达式两侧加空格。这是一个反例： + + s = sizeof( struct file ); + +当声明指针类型或者返回指针类型的函数时，“*”的首选使用方式是使之靠近变量名或者函 +数名，而不是靠近类型名。例子： + + char *linux_banner; + unsigned long long memparse(char *ptr, char **retptr); + char *match_strdup(substring_t *s); + +在大多数二元和三元操作符两侧使用一个空格，例如下面所有这些操作符： + + = + - < > * / % | & ^ <= >= == != ? : + +但是一元操作符后不要加空格： + & * + - ~ ! sizeof typeof alignof __attribute__ defined + +后缀自加和自减一元操作符前不加空格： + ++ -- + +前缀自加和自减一元操作符后不加空格： + ++ -- + +“.”和“->”结构体成员操作符前后不加空格。 + +不要在行尾留空白。有些可以自动缩进的编辑器会在新行的行首加入适量的空白，然后你 +就可以直接在那一行输入代码。不过假如你最后没有在那一行输入代码，有些编辑器就不 +会移除已经加入的空白，就像你故意留下一个只有空白的行。包含行尾空白的行就这样产 +生了。 + +当git发现补丁包含了行尾空白的时候会警告你，并且可以应你的要求去掉行尾空白；不过 +如果你是正在打一系列补丁，这样做会导致后面的补丁失败，因为你改变了补丁的上下文。 + + + 第四章：命名 + +C是一个简朴的语言，你的命名也应该这样。和Modula-2和Pascal程序员不同，C程序员不使 +用类似ThisVariableIsATemporaryCounter这样华丽的名字。C程序员会称那个变量为“tmp” +，这样写起来会更容易，而且至少不会令其难于理解。 + +不过，虽然混用大小写的名字是不提倡使用的，但是全局变量还是需要一个具描述性的名字 +。称一个全局函数为“foo”是一个难以饶恕的错误。 + +全局变量（只有当你真正需要它们的时候再用它）需要有一个具描述性的名字，就像全局函 +数。如果你有一个可以计算活动用户数量的函数，你应该叫它“count_active_users()”或者 +类似的名字，你不应该叫它“cntuser()”。 + +在函数名中包含函数类型（所谓的匈牙利命名法）是脑子出了问题——编译器知道那些类型而 +且能够检查那些类型，这样做只能把程序员弄糊涂了。难怪微软总是制造出有问题的程序。 + +本地变量名应该简短，而且能够表达相关的含义。如果你有一些随机的整数型的循环计数器 +，它应该被称为“i”。叫它“loop_counter”并无益处，如果它没有被误解的可能的话。类似 +的，“tmp”可以用来称呼任意类型的临时变量。 + +如果你怕混淆了你的本地变量名，你就遇到另一个问题了，叫做函数增长荷尔蒙失衡综合症 +。请看第六章（函数）。 + + + 第五章：Typedef + +不要使用类似“vps_t”之类的东西。 + +对结构体和指针使用typedef是一个错误。当你在代码里看到： + + vps_t a; + +这代表什么意思呢？ + +相反，如果是这样 + + struct virtual_container *a; + +你就知道“a”是什么了。 + +很多人认为typedef“能提高可读性”。实际不是这样的。它们只在下列情况下有用： + + (a) 完全不透明的对象（这种情况下要主动使用typedef来隐藏这个对象实际上是什么）。 + + 例如：“pte_t”等不透明对象，你只能用合适的访问函数来访问它们。 + + 注意！不透明性和“访问函数”本身是不好的。我们使用pte_t等类型的原因在于真的是 + 完全没有任何共用的可访问信息。 + + (b) 清楚的整数类型，如此，这层抽象就可以帮助消除到底是“int”还是“long”的混淆。 + + u8/u16/u32是完全没有问题的typedef，不过它们更符合类别(d)而不是这里。 + + 再次注意！要这样做，必须事出有因。如果某个变量是“unsigned long“，那么没有必要 + + typedef unsigned long myflags_t; + + 不过如果有一个明确的原因，比如它在某种情况下可能会是一个“unsigned int”而在 + 其他情况下可能为“unsigned long”，那么就不要犹豫，请务必使用typedef。 + + (c) 当你使用sparse按字面的创建一个新类型来做类型检查的时候。 + + (d) 和标准C99类型相同的类型，在某些例外的情况下。 + + 虽然让眼睛和脑筋来适应新的标准类型比如“uint32_t”不需要花很多时间，可是有些 + 人仍然拒绝使用它们。 + + 因此，Linux特有的等同于标准类型的“u8/u16/u32/u64”类型和它们的有符号类型是被 + 允许的——尽管在你自己的新代码中，它们不是强制要求要使用的。 + + 当编辑已经使用了某个类型集的已有代码时，你应该遵循那些代码中已经做出的选择。 + + (e) 可以在用户空间安全使用的类型。 + + 在某些用户空间可见的结构体里，我们不能要求C99类型而且不能用上面提到的“u32” + 类型。因此，我们在与用户空间共享的所有结构体中使用__u32和类似的类型。 + +可能还有其他的情况，不过基本的规则是永远不要使用typedef，除非你可以明确的应用上 +述某个规则中的一个。 + +总的来说，如果一个指针或者一个结构体里的元素可以合理的被直接访问到，那么它们就不 +应该是一个typedef。 + + + 第六章：函数 + +函数应该简短而漂亮，并且只完成一件事情。函数应该可以一屏或者两屏显示完（我们都知 +道ISO/ANSI屏幕大小是80x24），只做一件事情，而且把它做好。 + +一个函数的最大长度是和该函数的复杂度和缩进级数成反比的。所以，如果你有一个理论上 +很简单的只有一个很长（但是简单）的case语句的函数，而且你需要在每个case里做很多很 +小的事情，这样的函数尽管很长，但也是可以的。 + +不过，如果你有一个复杂的函数，而且你怀疑一个天分不是很高的高中一年级学生可能甚至 +搞不清楚这个函数的目的，你应该严格的遵守前面提到的长度限制。使用辅助函数，并为之 +取个具描述性的名字（如果你觉得它们的性能很重要的话，可以让编译器内联它们，这样的 +效果往往会比你写一个复杂函数的效果要好。） + +函数的另外一个衡量标准是本地变量的数量。此数量不应超过5－10个，否则你的函数就有 +问题了。重新考虑一下你的函数，把它分拆成更小的函数。人的大脑一般可以轻松的同时跟 +踪7个不同的事物，如果再增多的话，就会糊涂了。即便你聪颖过人，你也可能会记不清你2 +个星期前做过的事情。 + +在源文件里，使用空行隔开不同的函数。如果该函数需要被导出，它的EXPORT*宏应该紧贴 +在它的结束大括号之下。比如： + +int system_is_up(void) +{ + return system_state == SYSTEM_RUNNING; +} +EXPORT_SYMBOL(system_is_up); + +在函数原型中，包含函数名和它们的数据类型。虽然C语言里没有这样的要求，在Linux里这 +是提倡的做法，因为这样可以很简单的给读者提供更多的有价值的信息。 + + + 第七章：集中的函数退出途径 + +虽然被某些人声称已经过时，但是goto语句的等价物还是经常被编译器所使用，具体形式是 +无条件跳转指令。 + +当一个函数从多个位置退出并且需要做一些通用的清理工作的时候，goto的好处就显现出来 +了。 + +理由是： + +- 无条件语句容易理解和跟踪 +- 嵌套程度减小 +- 可以避免由于修改时忘记更新某个单独的退出点而导致的错误 +- 减轻了编译器的工作，无需删除冗余代码;) + +int fun(int a) +{ + int result = 0; + char *buffer = kmalloc(SIZE); + + if (buffer == NULL) + return -ENOMEM; + + if (condition1) { + while (loop1) { + ... + } + result = 1; + goto out; + } + ... +out: + kfree(buffer); + return result; +} + + 第八章：注释 + +注释是好的，不过有过度注释的危险。永远不要在注释里解释你的代码是如何运作的：更好 +的做法是让别人一看你的代码就可以明白，解释写的很差的代码是浪费时间。 + +一般的，你想要你的注释告诉别人你的代码做了什么，而不是怎么做的。也请你不要把注释 +放在一个函数体内部：如果函数复杂到你需要独立的注释其中的一部分，你很可能需要回到 +第六章看一看。你可以做一些小注释来注明或警告某些很聪明（或者槽糕）的做法，但不要 +加太多。你应该做的，是把注释放在函数的头部，告诉人们它做了什么，也可以加上它做这 +些事情的原因。 + +当注释内核API函数时，请使用kernel-doc格式。请看 +Documentation/kernel-doc-nano-HOWTO.txt和scripts/kernel-doc以获得详细信息。 + +Linux的注释风格是C89“/* ... */”风格。不要使用C99风格“// ...”注释。 + +长（多行）的首选注释风格是： + + /* + * This is the preferred style for multi-line + * comments in the Linux kernel source code. + * Please use it consistently. + * + * Description: A column of asterisks on the left side, + * with beginning and ending almost-blank lines. + */ + +注释数据也是很重要的，不管是基本类型还是衍生类型。为了方便实现这一点，每一行应只 +声明一个数据（不要使用逗号来一次声明多个数据）。这样你就有空间来为每个数据写一段 +小注释来解释它们的用途了。 + + + 第九章：你已经把事情弄糟了 + +这没什么，我们都是这样。可能你的使用了很长时间Unix的朋友已经告诉你“GNU emacs”能 +自动帮你格式化C源代码，而且你也注意到了，确实是这样，不过它所使用的默认值和我们 +想要的相去甚远（实际上，甚至比随机打的还要差——无数个猴子在GNU emacs里打字永远不 +会创造出一个好程序）（译注：请参考Infinite Monkey Theorem） + +所以你要么放弃GNU emacs，要么改变它让它使用更合理的设定。要采用后一个方案，你可 +以把下面这段粘贴到你的.emacs文件里。 + +(defun linux-c-mode () + "C mode with adjusted defaults for use with the Linux kernel." + (interactive) + (c-mode) + (c-set-style "K&R") + (setq tab-width 8) + (setq indent-tabs-mode t) + (setq c-basic-offset 8)) + +这样就定义了M-x linux-c-mode命令。当你hack一个模块的时候，如果你把字符串 +-*- linux-c -*-放在头两行的某个位置，这个模式将会被自动调用。如果你希望在你修改 +/usr/src/linux里的文件时魔术般自动打开linux-c-mode的话，你也可能需要添加 + +(setq auto-mode-alist (cons '("/usr/src/linux.*/.*\\.[ch]$" . linux-c-mode) + auto-mode-alist)) + +到你的.emacs文件里。 + +不过就算你尝试让emacs正确的格式化代码失败了，也并不意味着你失去了一切：还可以用“ +indent”。 + +不过，GNU indent也有和GNU emacs一样有问题的设定，所以你需要给它一些命令选项。不 +过，这还不算太糟糕，因为就算是GNU indent的作者也认同K&R的权威性（GNU的人并不是坏 +人，他们只是在这个问题上被严重的误导了），所以你只要给indent指定选项“-kr -i8” +（代表“K&R，8个字符缩进”），或者使用“scripts/Lindent”，这样就可以以最时髦的方式 +缩进源代码。 + +“indent”有很多选项，特别是重新格式化注释的时候，你可能需要看一下它的手册页。不过 +记住：“indent”不能修正坏的编程习惯。 + + + 第十章：Kconfig配置文件 + +对于遍布源码树的所有Kconfig*配置文件来说，它们缩进方式与C代码相比有所不同。紧挨 +在“config”定义下面的行缩进一个制表符，帮助信息则再多缩进2个空格。比如： + +config AUDIT + bool "Auditing support" + depends on NET + help + Enable auditing infrastructure that can be used with another + kernel subsystem, such as SELinux (which requires this for + logging of avc messages output). Does not do system-call + auditing without CONFIG_AUDITSYSCALL. + +仍然被认为不够稳定的功能应该被定义为依赖于“EXPERIMENTAL”： + +config SLUB + depends on EXPERIMENTAL && !ARCH_USES_SLAB_PAGE_STRUCT + bool "SLUB (Unqueued Allocator)" + ... + +而那些危险的功能（比如某些文件系统的写支持）应该在它们的提示字符串里显著的声明这 +一点： + +config ADFS_FS_RW + bool "ADFS write support (DANGEROUS)" + depends on ADFS_FS + ... + +要查看配置文件的完整文档，请看Documentation/kbuild/kconfig-language.txt。 + + + 第十一章：数据结构 + +如果一个数据结构，在创建和销毁它的单线执行环境之外可见，那么它必须要有一个引用计 +数器。内核里没有垃圾收集（并且内核之外的垃圾收集慢且效率低下），这意味着你绝对需 +要记录你对这种数据结构的使用情况。 + +引用计数意味着你能够避免上锁，并且允许多个用户并行访问这个数据结构——而不需要担心 +这个数据结构仅仅因为暂时不被使用就消失了，那些用户可能不过是沉睡了一阵或者做了一 +些其他事情而已。 + +注意上锁不能取代引用计数。上锁是为了保持数据结构的一致性，而引用计数是一个内存管 +理技巧。通常二者都需要，不要把两个搞混了。 + +很多数据结构实际上有2级引用计数，它们通常有不同“类”的用户。子类计数器统计子类用 +户的数量，每当子类计数器减至零时，全局计数器减一。 + +这种“多级引用计数”的例子可以在内存管理（“struct mm_struct”：mm_users和mm_count） +和文件系统（“struct super_block”：s_count和s_active）中找到。 + +记住：如果另一个执行线索可以找到你的数据结构，但是这个数据结构没有引用计数器，这 +里几乎肯定是一个bug。 + + + 第十二章：宏，枚举和RTL + +用于定义常量的宏的名字及枚举里的标签需要大写。 + +#define CONSTANT 0x12345 + +在定义几个相关的常量时，最好用枚举。 + +宏的名字请用大写字母，不过形如函数的宏的名字可以用小写字母。 + +一般的，如果能写成内联函数就不要写成像函数的宏。 + +含有多个语句的宏应该被包含在一个do-while代码块里： + +#define macrofun(a, b, c) \ + do { \ + if (a == 5) \ + do_this(b, c); \ + } while (0) + +使用宏的时候应避免的事情： + +1) 影响控制流程的宏： + +#define FOO(x) \ + do { \ + if (blah(x) < 0) \ + return -EBUGGERED; \ + } while(0) + +非常不好。它看起来像一个函数，不过却能导致“调用”它的函数退出；不要打乱读者大脑里 +的语法分析器。 + +2) 依赖于一个固定名字的本地变量的宏： + +#define FOO(val) bar(index, val) + +可能看起来像是个不错的东西，不过它非常容易把读代码的人搞糊涂，而且容易导致看起来 +不相关的改动带来错误。 + +3) 作为左值的带参数的宏： FOO(x) = y；如果有人把FOO变成一个内联函数的话，这种用 +法就会出错了。 + +4) 忘记了优先级：使用表达式定义常量的宏必须将表达式置于一对小括号之内。带参数的 +宏也要注意此类问题。 + +#define CONSTANT 0x4000 +#define CONSTEXP (CONSTANT | 3) + +cpp手册对宏的讲解很详细。Gcc internals手册也详细讲解了RTL（译注：register +transfer language），内核里的汇编语言经常用到它。 + + + 第十三章：打印内核消息 + +内核开发者应该是受过良好教育的。请一定注意内核信息的拼写，以给人以好的印象。不要 +用不规范的单词比如“dont”，而要用“do not”或者“don't”。保证这些信息简单、明了、无 +歧义。 + +内核信息不必以句号（译注：英文句号，即点）结束。 + +在小括号里打印数字(%d)没有任何价值，应该避免这样做。 + +<linux/device.h>里有一些驱动模型诊断宏，你应该使用它们，以确保信息对应于正确的 +设备和驱动，并且被标记了正确的消息级别。这些宏有：dev_err(), dev_warn(), +dev_info()等等。对于那些不和某个特定设备相关连的信息，<linux/kernel.h>定义了 +pr_debug()和pr_info()。 + +写出好的调试信息可以是一个很大的挑战；当你写出来之后，这些信息在远程除错的时候 +就会成为极大的帮助。当DEBUG符号没有被定义的时候，这些信息不应该被编译进内核里 +（也就是说，默认地，它们不应该被包含在内）。如果你使用dev_dbg()或者pr_debug()， +就能自动达到这个效果。很多子系统拥有Kconfig选项来启用-DDEBUG。还有一个相关的惯例 +是使用VERBOSE_DEBUG来添加dev_vdbg()消息到那些已经由DEBUG启用的消息之上。 + + + 第十四章：分配内存 + +内核提供了下面的一般用途的内存分配函数：kmalloc()，kzalloc()，kcalloc()和 +vmalloc()。请参考API文档以获取有关它们的详细信息。 + +传递结构体大小的首选形式是这样的： + + p = kmalloc(sizeof(*p), ...); + +另外一种传递方式中，sizeof的操作数是结构体的名字，这样会降低可读性，并且可能会引 +入bug。有可能指针变量类型被改变时，而对应的传递给内存分配函数的sizeof的结果不变。 + +强制转换一个void指针返回值是多余的。C语言本身保证了从void指针到其他任何指针类型 +的转换是没有问题的。 + + + 第十五章：内联弊病 + +有一个常见的误解是内联函数是gcc提供的可以让代码运行更快的一个选项。虽然使用内联 +函数有时候是恰当的（比如作为一种替代宏的方式，请看第十二章），不过很多情况下不是 +这样。inline关键字的过度使用会使内核变大，从而使整个系统运行速度变慢。因为大内核 +会占用更多的指令高速缓存（译注：一级缓存通常是指令缓存和数据缓存分开的）而且会导 +致pagecache的可用内存减少。想象一下，一次pagecache未命中就会导致一次磁盘寻址，将 +耗时5毫秒。5毫秒的时间内CPU能执行很多很多指令。 + +一个基本的原则是如果一个函数有3行以上，就不要把它变成内联函数。这个原则的一个例 +外是，如果你知道某个参数是一个编译时常量，而且因为这个常量你确定编译器在编译时能 +优化掉你的函数的大部分代码，那仍然可以给它加上inline关键字。kmalloc()内联函数就 +是一个很好的例子。 + +人们经常主张给static的而且只用了一次的函数加上inline，如此不会有任何损失，因为没 +有什么好权衡的。虽然从技术上说这是正确的，但是实际上这种情况下即使不加inline gcc +也可以自动使其内联。而且其他用户可能会要求移除inline，由此而来的争论会抵消inline +自身的潜在价值，得不偿失。 + + + 第十六章：函数返回值及命名 + +函数可以返回很多种不同类型的值，最常见的一种是表明函数执行成功或者失败的值。这样 +的一个值可以表示为一个错误代码整数（-Exxx＝失败，0＝成功）或者一个“成功”布尔值（ +0＝失败，非0＝成功）。 + +混合使用这两种表达方式是难于发现的bug的来源。如果C语言本身严格区分整形和布尔型变 +量，那么编译器就能够帮我们发现这些错误……不过C语言不区分。为了避免产生这种bug，请 +遵循下面的惯例： + + 如果函数的名字是一个动作或者强制性的命令，那么这个函数应该返回错误代码整 + 数。如果是一个判断，那么函数应该返回一个“成功”布尔值。 + +比如，“add work”是一个命令，所以add_work()函数在成功时返回0，在失败时返回-EBUSY。 +类似的，因为“PCI device present”是一个判断，所以pci_dev_present()函数在成功找到 +一个匹配的设备时应该返回1，如果找不到时应该返回0。 + +所有导出（译注：EXPORT）的函数都必须遵守这个惯例，所有的公共函数也都应该如此。私 +有（static）函数不需要如此，但是我们也推荐这样做。 + +返回值是实际计算结果而不是计算是否成功的标志的函数不受此惯例的限制。一般的，他们 +通过返回一些正常值范围之外的结果来表示出错。典型的例子是返回指针的函数，他们使用 +NULL或者ERR_PTR机制来报告错误。 + + + 第十七章：不要重新发明内核宏 + +头文件include/linux/kernel.h包含了一些宏，你应该使用它们，而不要自己写一些它们的 +变种。比如，如果你需要计算一个数组的长度，使用这个宏 + + #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0])) + +类似的，如果你要计算某结构体成员的大小，使用 + + #define FIELD_SIZEOF(t, f) (sizeof(((t*)0)->f)) + +还有可以做严格的类型检查的min()和max()宏，如果你需要可以使用它们。你可以自己看看 +那个头文件里还定义了什么你可以拿来用的东西，如果有定义的话，你就不应在你的代码里 +自己重新定义。 + + + 第十八章：编辑器模式行和其他需要罗嗦的事情 + +有一些编辑器可以解释嵌入在源文件里的由一些特殊标记标明的配置信息。比如，emacs +能够解释被标记成这样的行： + +-*- mode: c -*- + +或者这样的： + +/* +Local Variables: +compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c" +End: +*/ + +Vim能够解释这样的标记： + +/* vim:set sw=8 noet */ + +不要在源代码中包含任何这样的内容。每个人都有他自己的编辑器配置，你的源文件不应 +该覆盖别人的配置。这包括有关缩进和模式配置的标记。人们可以使用他们自己定制的模 +式，或者使用其他可以产生正确的缩进的巧妙方法。 + + + + 附录 I：参考 + +The C Programming Language, 第二版, 作者Brian W. Kernighan和Denni +M. Ritchie. Prentice Hall, Inc., 1988. ISBN 0-13-110362-8 (软皮), +0-13-110370-9 (硬皮). URL: http://cm.bell-labs.com/cm/cs/cbook/ + +The Practice of Programming 作者Brian W. Kernighan和Rob Pike. Addison-Wesley, +Inc., 1999. ISBN 0-201-61586-X. URL: http://cm.bell-labs.com/cm/cs/tpop/ + +cpp，gcc，gcc internals和indent的GNU手册——和K&R及本文相符合的部分，全部可以在 +http://www.gnu.org/manual/找到 + +WG14是C语言的国际标准化工作组，URL: http://www.open-std.org/JTC1/SC22/WG14/ + +Kernel CodingStyle，作者greg@kroah.com发表于OLS 2002： +http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/ + +-- +最后更新于2007年7月13日。 diff --git a/Documentation/zh_CN/HOWTO b/Documentation/zh_CN/HOWTO index 48fc67bfbe3..3d80e8af36e 100644 --- a/Documentation/zh_CN/HOWTO +++ b/Documentation/zh_CN/HOWTO @@ -1,10 +1,10 @@ Chinese translated version of Documentation/HOWTO If you have any comment or update to the content, please contact the -original document maintainer directly. However, if you have problem +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 there is problem with translation. +help. Contact the Chinese maintainer if this translation is outdated +or if there is a problem with the translation. Maintainer: Greg Kroah-Hartman <greg@kroah.com> Chinese maintainer: Li Yang <leoli@freescale.com> @@ -85,7 +85,7 @@ Linux内核源代码都是在GPL（通用公共许可证）的保护下发布的 Linux内核代码中包含有大量的文档。这些文档对于学习如何与内核社区互动有着 不可估量的价值。当一个新的功能被加入内核，最好把解释如何使用这个功能的文 档也放进内核。当内核的改动导致面向用户空间的接口发生变化时，最好将相关信 -息或手册页(manpages)的补丁发到mtk-manpages@gmx.net，以向手册页(manpages) +息或手册页(manpages)的补丁发到mtk.manpages@gmail.com，以向手册页(manpages) 的维护者解释这些变化。 以下是内核代码中需要阅读的文档： @@ -218,6 +218,8 @@ kernel.org网站的pub/linux/kernel/v2.6/目录下找到它。它的开发遵循 时，一个新的-rc版本就会被发布。计划是每周都发布新的-rc版本。 - 这个过程一直持续下去直到内核被认为达到足够稳定的状态，持续时间大概是 6个星期。 + - 以下地址跟踪了在每个-rc发布中发现的退步列表： + http://kernelnewbies.org/known_regressions 关于内核发布，值得一提的是Andrew Morton在linux-kernel邮件列表中如是说： “没有人知道新内核何时会被发布，因为发布是根据已知bug的情况来决定 diff --git a/Documentation/zh_CN/SubmittingDrivers b/Documentation/zh_CN/SubmittingDrivers new file mode 100644 index 00000000000..5f4815c63ec --- /dev/null +++ b/Documentation/zh_CN/SubmittingDrivers @@ -0,0 +1,168 @@ +Chinese translated version of Documentation/SubmittingDrivers + +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: Li Yang <leo@zh-kernel.org> +--------------------------------------------------------------------- +Documentation/SubmittingDrivers 的中文翻译 + +如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 +交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 +译存在问题，请联系中文版维护者。 + +中文版维护者： 李阳 Li Yang <leo@zh-kernel.org> +中文版翻译者： 李阳 Li Yang <leo@zh-kernel.org> +中文版校译者： 陈琦 Maggie Chen <chenqi@beyondsoft.com> + 王聪 Wang Cong <xiyou.wangcong@gmail.com> + 张巍 Zhang Wei <Wei.Zhang@freescale.com> + +以下为正文 +--------------------------------------------------------------------- + +如何向 Linux 内核提交驱动程序 +----------------------------- + +这篇文档将会解释如何向不同的内核源码树提交设备驱动程序。请注意，如果你感 +兴趣的是显卡驱动程序，你也许应该访问 XFree86 项目(http://www.xfree86.org/) +和／或 X.org 项目 (http://x.org)。 + +另请参阅 Documentation/SubmittingPatches 文档。 + + +分配设备号 +---------- + +块设备和字符设备的主设备号与从设备号是由 Linux 命名编号分配权威 LANANA（ +现在是 Torben Mathiasen）负责分配。申请的网址是 http://www.lanana.org/。 +即使不准备提交到主流内核的设备驱动也需要在这里分配设备号。有关详细信息， +请参阅 Documentation/devices.txt。 + +如果你使用的不是已经分配的设备号，那么当你提交设备驱动的时候，它将会被强 +制分配一个新的设备号，即便这个设备号和你之前发给客户的截然不同。 + +设备驱动的提交对象 +------------------ + +Linux 2.0: + 此内核源码树不接受新的驱动程序。 + +Linux 2.2: + 此内核源码树不接受新的驱动程序。 + +Linux 2.4: + 如果所属的代码领域在内核的 MAINTAINERS 文件中列有一个总维护者， + 那么请将驱动程序提交给他。如果此维护者没有回应或者你找不到恰当的 + 维护者，那么请联系 Willy Tarreau <w@1wt.eu>。 + +Linux 2.6: + 除了遵循和 2.4 版内核同样的规则外，你还需要在 linux-kernel 邮件 + 列表上跟踪最新的 API 变化。向 Linux 2.6 内核提交驱动的顶级联系人 + 是 Andrew Morton <akpm@osdl.org>。 + +决定设备驱动能否被接受的条件 +---------------------------- + +许可： 代码必须使用 GNU 通用公开许可证 (GPL) 提交给 Linux，但是 + 我们并不要求 GPL 是唯一的许可。你或许会希望同时使用多种 + 许可证发布，如果希望驱动程序可以被其他开源社区（比如BSD） + 使用。请参考 include/linux/module.h 文件中所列出的可被 + 接受共存的许可。 + +版权： 版权所有者必须同意使用 GPL 许可。最好提交者和版权所有者 + 是相同个人或实体。否则，必需列出授权使用 GPL 的版权所有 + 人或实体，以备验证之需。 + +接口： 如果你的驱动程序使用现成的接口并且和其他同类的驱动程序行 + 为相似，而不是去发明无谓的新接口，那么它将会更容易被接受。 + 如果你需要一个 Linux 和 NT 的通用驱动接口，那么请在用 + 户空间实现它。 + +代码： 请使用 Documentation/CodingStyle 中所描述的 Linux 代码风 + 格。如果你的某些代码段（例如那些与 Windows 驱动程序包共 + 享的代码段）需要使用其他格式，而你却只希望维护一份代码， + 那么请将它们很好地区分出来，并且注明原因。 + +可移植性： 请注意，指针并不永远是 32 位的，不是所有的计算机都使用小 + 尾模式 (little endian) 存储数据，不是所有的人都拥有浮点 + 单元，不要随便在你的驱动程序里嵌入 x86 汇编指令。只能在 + x86 上运行的驱动程序一般是不受欢迎的。虽然你可能只有 x86 + 硬件，很难测试驱动程序在其他平台上是否可用，但是确保代码 + 可以被轻松地移植却是很简单的。 + +清晰度： 做到所有人都能修补这个驱动程序将会很有好处，因为这样你将 + 会直接收到修复的补丁而不是 bug 报告。如果你提交一个试图 + 隐藏硬件工作机理的驱动程序，那么它将会被扔进废纸篓。 + +电源管理： 因为 Linux 正在被很多移动设备和桌面系统使用，所以你的驱 + 动程序也很有可能被使用在这些设备上。它应该支持最基本的电 + 源管理，即在需要的情况下实现系统级休眠和唤醒要用到的 + .suspend 和 .resume 函数。你应该检查你的驱动程序是否能正 + 确地处理休眠与唤醒，如果实在无法确认，请至少把 .suspend + 函数定义成返回 -ENOSYS（功能未实现）错误。你还应该尝试确 + 保你的驱动在什么都不干的情况下将耗电降到最低。要获得驱动 + 程序测试的指导，请参阅 + Documentation/power/drivers-testing.txt。有关驱动程序电 + 源管理问题相对全面的概述，请参阅 + Documentation/power/devices.txt。 + +管理： 如果一个驱动程序的作者还在进行有效的维护，那么通常除了那 + 些明显正确且不需要任何检查的补丁以外，其他所有的补丁都会 + 被转发给作者。如果你希望成为驱动程序的联系人和更新者，最 + 好在代码注释中写明并且在 MAINTAINERS 文件中加入这个驱动 + 程序的条目。 + +不影响设备驱动能否被接受的条件 +------------------------------ + +供应商： 由硬件供应商来维护驱动程序通常是一件好事。不过，如果源码 + 树里已经有其他人提供了可稳定工作的驱动程序，那么请不要期 + 望“我是供应商”会成为内核改用你的驱动程序的理由。理想的情 + 况是：供应商与现有驱动程序的作者合作，构建一个统一完美的 + 驱动程序。 + +作者： 驱动程序是由大的 Linux 公司研发还是由你个人编写，并不影 + 响其是否能被内核接受。没有人对内核源码树享有特权。只要你 + 充分了解内核社区，你就会发现这一点。 + + +资源列表 +-------- + +Linux 内核主源码树： + ftp.??.kernel.org:/pub/linux/kernel/... + ?? == 你的国家代码，例如 "cn"、"us"、"uk"、"fr" 等等 + +Linux 内核邮件列表： + linux-kernel@vger.kernel.org + [可通过向majordomo@vger.kernel.org发邮件来订阅] + +Linux 设备驱动程序，第三版（探讨 2.6.10 版内核）： + http://lwn.net/Kernel/LDD3/ （免费版） + +LWN.net: + 每周内核开发活动摘要 - http://lwn.net/ + 2.6 版中 API 的变更： + http://lwn.net/Articles/2.6-kernel-api/ + 将旧版内核的驱动程序移植到 2.6 版： + http://lwn.net/Articles/driver-porting/ + +KernelTrap： + Linux 内核的最新动态以及开发者访谈 + http://kerneltrap.org/ + +内核新手(KernelNewbies): + 为新的内核开发者提供文档和帮助 + http://kernelnewbies.org/ + +Linux USB项目： + http://www.linux-usb.org/ + +写内核驱动的“不要”（Arjan van de Ven著）: + http://www.fenrus.org/how-to-not-write-a-device-driver-paper.pdf + +内核清洁工 (Kernel Janitor): + http://janitor.kernelnewbies.org/ diff --git a/Documentation/zh_CN/SubmittingPatches b/Documentation/zh_CN/SubmittingPatches new file mode 100644 index 00000000000..985c92e20b7 --- /dev/null +++ b/Documentation/zh_CN/SubmittingPatches @@ -0,0 +1,416 @@ +Chinese translated version of Documentation/SubmittingPatches + +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: TripleX Chung <triplex@zh-kernel.org> +--------------------------------------------------------------------- +Documentation/SubmittingPatches 的中文翻译 + +如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 +交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 +译存在问题，请联系中文版维护者。 + +中文版维护者： 钟宇 TripleX Chung <triplex@zh-kernel.org> +中文版翻译者： 钟宇 TripleX Chung <triplex@zh-kernel.org> +中文版校译者： 李阳 Li Yang <leo@zh-kernel.org> + 王聪 Wang Cong <xiyou.wangcong@gmail.com> + +以下为正文 +--------------------------------------------------------------------- + + 如何让你的改动进入内核 + 或者 + 获得亲爱的 Linus Torvalds 的关注和处理 +---------------------------------- + +对于想要将改动提交到 Linux 内核的个人或者公司来说，如果不熟悉“规矩”， +提交的流程会让人畏惧。本文档收集了一系列建议，这些建议可以大大的提高你 +的改动被接受的机会。 +阅读 Documentation/SubmitChecklist 来获得在提交代码前需要检查的项目的列 +表。如果你在提交一个驱动程序，那么同时阅读一下 +Documentation/SubmittingDrivers 。 + + +-------------------------- +第一节 - 创建并发送你的改动 +-------------------------- + +1) "diff -up" +----------- + +使用 "diff -up" 或者 "diff -uprN" 来创建补丁。 + +所有内核的改动，都是以补丁的形式呈现的，补丁由 diff(1) 生成。创建补丁的 +时候，要确认它是以 "unified diff" 格式创建的，这种格式由 diff(1) 的 '-u' +参数生成。而且，请使用 '-p' 参数，那样会显示每个改动所在的C函数，使得 +产生的补丁容易读得多。补丁应该基于内核源代码树的根目录，而不是里边的任 +何子目录。 +为一个单独的文件创建补丁，一般来说这样做就够了： + + SRCTREE= linux-2.6 + MYFILE= drivers/net/mydriver.c + + cd $SRCTREE + cp $MYFILE $MYFILE.orig + vi $MYFILE # make your change + cd .. + diff -up $SRCTREE/$MYFILE{.orig,} > /tmp/patch + +为多个文件创建补丁，你可以解开一个没有修改过的内核源代码树，然后和你自 +己的代码树之间做 diff 。例如： + + MYSRC= /devel/linux-2.6 + + tar xvfz linux-2.6.12.tar.gz + mv linux-2.6.12 linux-2.6.12-vanilla + diff -uprN -X linux-2.6.12-vanilla/Documentation/dontdiff \ + linux-2.6.12-vanilla $MYSRC > /tmp/patch + +"dontdiff" 是内核在编译的时候产生的文件的列表，列表中的文件在 diff(1) +产生的补丁里会被跳过。"dontdiff" 文件被包含在2.6.12和之后版本的内核源代 +码树中。对于更早的内核版本，你可以从 +<http://www.xenotime.net/linux/doc/dontdiff> 获取它。 +确定你的补丁里没有包含任何不属于这次补丁提交的额外文件。记得在用diff(1) +生成补丁之后，审阅一次补丁，以确保准确。 +如果你的改动很散乱，你应该研究一下如何将补丁分割成独立的部分，将改动分 +割成一系列合乎逻辑的步骤。这样更容易让其他内核开发者审核，如果你想你的 +补丁被接受，这是很重要的。下面这些脚本能够帮助你做这件事情： +Quilt: +http://savannah.nongnu.org/projects/quilt + +Andrew Morton 的补丁脚本: +http://www.zip.com.au/~akpm/linux/patches/ +作为这些脚本的替代，quilt 是值得推荐的补丁管理工具(看上面的链接)。 + +2)描述你的改动。 +描述你的改动包含的技术细节。 + +要多具体就写多具体。最糟糕的描述可能是像下面这些语句：“更新了某驱动程 +序”，“修正了某驱动程序的bug”，或者“这个补丁包含了某子系统的修改，请 +使用。” + +如果你的描述开始变长，这表示你也许需要拆分你的补丁了，请看第3小节， +继续。 + +3)拆分你的改动 + +将改动拆分，逻辑类似的放到同一个补丁文件里。 + +例如，如果你的改动里同时有bug修正和性能优化，那么把这些改动才分到两个或 +者更多的补丁文件中。如果你的改动包含对API的修改，并且修改了驱动程序来适 +应这些新的API，那么把这些修改分成两个补丁。 + +另一方面，如果你将一个单独的改动做成多个补丁文件，那么将它们合并成一个 +单独的补丁文件。这样一个逻辑上单独的改动只被包含在一个补丁文件里。 + +如果有一个补丁依赖另外一个补丁来完成它的改动，那没问题。简单的在你的补 +丁描述里指出“这个补丁依赖某补丁”就好了。 + +如果你不能将补丁浓缩成更少的文件，那么每次大约发送出15个，然后等待审查 +和整合。 + +4)选择 e-mail 的收件人 + +看一遍 MAINTAINERS 文件和源代码，看看你所的改动所在的内核子系统有没有指 +定的维护者。如果有，给他们发e-mail。 + +如果没有找到维护者，或者维护者没有反馈，将你的补丁发送到内核开发者主邮 +件列表 linux-kernel@vger.kernel.org。大部分的内核开发者都跟踪这个邮件列 +表，可以评价你的改动。 + +每次不要发送超过15个补丁到 vger 邮件列表！！！ + +Linus Torvalds 是决定改动能否进入 Linux 内核的最终裁决者。他的 e-mail +地址是 <torvalds@linux-foundation.org> 。他收到的 e-mail 很多，所以一般 +的说，最好别给他发 e-mail。 + +那些修正bug，“显而易见”的修改或者是类似的只需要很少讨论的补丁可以直接 +发送或者CC给Linus。那些需要讨论或者没有很清楚的好处的补丁，一般先发送到 +linux-kernel邮件列表。只有当补丁被讨论得差不多了，才提交给Linus。 + +5)选择CC( e-mail 抄送)列表 + +除非你有理由不这样做，否则CC linux-kernel@vger.kernel.org。 + +除了 Linus 之外，其他内核开发者也需要注意到你的改动，这样他们才能评论你 +的改动并提供代码审查和建议。linux-kernel 是 Linux 内核开发者主邮件列表 +。其它的邮件列表为特定的子系统提供服务，比如 USB，framebuffer 设备，虚 +拟文件系统，SCSI 子系统，等等。查看 MAINTAINERS 文件来获得和你的改动有 +关的邮件列表。 + +Majordomo lists of VGER.KERNEL.ORG at: + <http://vger.kernel.org/vger-lists.html> + +如果改动影响了用户空间和内核之间的接口，请给 MAN-PAGES 的维护者（列在 +MAITAINERS 文件里的）发送一个手册页（man-pages）补丁，或者至少通知一下改 +变，让一些信息有途径进入手册页。 + +即使在第四步的时候，维护者没有作出回应，也要确认在修改他们的代码的时候 +，一直将维护者拷贝到CC列表中。 + +对于小的补丁，你也许会CC到 Adrian Bunk 管理的搜集琐碎补丁的邮件列表 +(Trivial Patch Monkey)trivial@kernel.org，那里专门收集琐碎的补丁。下面这样 +的补丁会被看作“琐碎的”补丁： + 文档的拼写修正。 + 修正会影响到 grep(1) 的拼写。 + 警告信息修正(频繁的打印无用的警告是不好的。) + 编译错误修正（代码逻辑的确是对的，只是编译有问题。） + 运行时修正（只要真的修正了错误。） + 移除使用了被废弃的函数/宏的代码(例如 check_region。) + 联系方式和文档修正。 + 用可移植的代码替换不可移植的代码（即使在体系结构相关的代码中，既然有 + 人拷贝，只要它是琐碎的） + 任何文件的作者/维护者对该文件的改动（例如 patch monkey 在重传模式下） + +URL: <http://www.kernel.org/pub/linux/kernel/people/bunk/trivial/> + +(译注，关于“琐碎补丁”的一些说明：因为原文的这一部分写得比较简单，所以不得不 +违例写一下译注。"trivial"这个英文单词的本意是“琐碎的，不重要的。”但是在这里 +有稍微有一些变化，例如对一些明显的NULL指针的修正，属于运行时修正，会被归类 +到琐碎补丁里。虽然NULL指针的修正很重要，但是这样的修正往往很小而且很容易得到 +检验，所以也被归入琐碎补丁。琐碎补丁更精确的归类应该是 +“simple, localized & easy to verify”，也就是说简单的，局部的和易于检验的。 +trivial@kernel.org邮件列表的目的是针对这样的补丁，为提交者提供一个中心，来 +降低提交的门槛。) + +6)没有 MIME 编码，没有链接，没有压缩，没有附件，只有纯文本。 + +Linus 和其他的内核开发者需要阅读和评论你提交的改动。对于内核开发者来说 +，可以“引用”你的改动很重要，使用一般的 e-mail 工具，他们就可以在你的 +代码的任何位置添加评论。 + +因为这个原因，所有的提交的补丁都是 e-mail 中“内嵌”的。 +警告：如果你使用剪切-粘贴你的补丁，小心你的编辑器的自动换行功能破坏你的 +补丁。 + +不要将补丁作为 MIME 编码的附件，不管是否压缩。很多流行的 e-mail 软件不 +是任何时候都将 MIME 编码的附件当作纯文本发送的，这会使得别人无法在你的 +代码中加评论。另外，MIME 编码的附件会让 Linus 多花一点时间来处理，这就 +降低了你的改动被接受的可能性。 + +警告：一些邮件软件，比如 Mozilla 会将你的信息以如下格式发送： +---- 邮件头 ---- +Content-Type: text/plain; charset=us-ascii; format=flowed +---- 邮件头 ---- +问题在于 “format=flowed” 会让接收端的某些邮件软件将邮件中的制表符替换 +成空格以及做一些类似的替换。这样，你发送的时候看起来没问题的补丁就被破 +坏了。 + +要修正这个问题，只需要将你的 mozilla 的 defaults/pref/mailnews.js 文件 +里的 +pref("mailnews.send_plaintext_flowed", false); // RFC 2646======= +修改成 +pref("mailnews.display.disable_format_flowed_support", true); +就可以了。 + +7) e-mail 的大小 + +给 Linus 发送补丁的时候，永远按照第6小节说的做。 + +大的改动对邮件列表不合适，对某些维护者也不合适。如果你的补丁，在不压缩 +的情况下，超过了40kB，那么你最好将补丁放在一个能通过 internet 访问的服 +务器上，然后用指向你的补丁的 URL 替代。 + +8) 指出你的内核版本 + +在标题和在补丁的描述中，指出补丁对应的内核的版本，是很重要的。 + +如果补丁不能干净的在最新版本的内核上打上，Linus 是不会接受它的。 + +9) 不要气馁，继续提交。 + +当你提交了改动以后，耐心地等待。如果 Linus 喜欢你的改动并且同意它，那么 +它将在下一个内核发布版本中出现。 + +然而，如果你的改动没有出现在下一个版本的内核中，可能有若干原因。减少那 +些原因，修正错误，重新提交更新后的改动，是你自己的工作。 + +Linus不给出任何评论就“丢弃”你的补丁是常见的事情。在系统中这样的事情很 +平常。如果他没有接受你的补丁，也许是由于以下原本： +* 你的补丁不能在最新版本的内核上干净的打上。 +* 你的补丁在 linux-kernel 邮件列表中没有得到充分的讨论。 +* 风格问题（参照第2小节） +* 邮件格式问题（重读本节） +* 你的改动有技术问题。 +* 他收到了成吨的 e-mail，而你的在混乱中丢失了。 +* 你让人为难。 + +有疑问的时候，在 linux-kernel 邮件列表上请求评论。 + +10) 在标题上加上 PATCH 的字样 + +Linus 和 linux-kernel 邮件列表的 e-mail 流量都很高，一个通常的约定是标 +题行以 [PATCH] 开头。这样可以让 Linus 和其他内核开发人员可以从 e-mail +的讨论中很轻易的将补丁分辨出来。 + +11）为你的工作签名 + +为了加强对谁做了何事的追踪，尤其是对那些透过好几层的维护者的补丁，我们 +建议在发送出去的补丁上加一个 “sign-off” 的过程。 + +"sign-off" 是在补丁的注释的最后的简单的一行文字，认证你编写了它或者其他 +人有权力将它作为开放源代码的补丁传递。规则很简单：如果你能认证如下信息 +： + 开发者来源证书 1.1 + 对于本项目的贡献，我认证如下信息： + （a）这些贡献是完全或者部分的由我创建，我有权利以文件中指出 + 的开放源代码许可证提交它；或者 + （b）这些贡献基于以前的工作，据我所知，这些以前的工作受恰当的开放 + 源代码许可证保护，而且，根据许可证，我有权提交修改后的贡献， + 无论是完全还是部分由我创造，这些贡献都使用同一个开放源代码许可证 + （除非我被允许用其它的许可证），正如文件中指出的；或者 + （c）这些贡献由认证（a），（b）或者（c）的人直接提供给我，而 + 且我没有修改它。 + （d）我理解并同意这个项目和贡献是公开的，贡献的记录（包括我 + 一起提交的个人记录，包括 sign-off ）被永久维护并且可以和这个项目 + 或者开放源代码的许可证同步地再发行。 + 那么加入这样一行： + Signed-off-by: Random J Developer <random@developer.example.org> + +使用你的真名（抱歉，不能使用假名或者匿名。） + +有人在最后加上标签。现在这些东西会被忽略，但是你可以这样做，来标记公司 +内部的过程，或者只是指出关于 sign-off 的一些特殊细节。 + +12）标准补丁格式 + +标准的补丁，标题行是： + Subject: [PATCH 001/123] 子系统:一句话概述 + +标准补丁的信体存在如下部分： + + - 一个 "from" 行指出补丁作者。 + + - 一个空行 + + - 说明的主体，这些说明文字会被拷贝到描述该补丁的永久改动记录里。 + + - 一个由"---"构成的标记行 + + - 不合适放到改动记录里的额外的注解。 + + - 补丁本身（diff 输出） + +标题行的格式，使得对标题行按字母序排序非常的容易 - 很多 e-mail 客户端都 +可以支持 - 因为序列号是用零填充的，所以按数字排序和按字母排序是一样的。 + +e-mail 标题中的“子系统”标识哪个内核子系统将被打补丁。 + +e-mail 标题中的“一句话概述”扼要的描述 e-mail 中的补丁。“一句话概述” +不应该是一个文件名。对于一个补丁系列（“补丁系列”指一系列的多个相关补 +丁），不要对每个补丁都使用同样的“一句话概述”。 + +记住 e-mail 的“一句话概述”会成为该补丁的全局唯一标识。它会蔓延到 git +的改动记录里。然后“一句话概述”会被用在开发者的讨论里，用来指代这个补 +丁。用户将希望通过 google 来搜索"一句话概述"来找到那些讨论这个补丁的文 +章。 + +一些标题的例子： + + Subject: [patch 2/5] ext2: improve scalability of bitmap searching + Subject: [PATCHv2 001/207] x86: fix eflags tracking + +"from" 行是信体里的最上面一行，具有如下格式： + From: Original Author <author@example.com> + +"from" 行指明在永久改动日志里，谁会被确认为作者。如果没有 "from" 行，那 +么邮件头里的 "From: " 行会被用来决定改动日志中的作者。 + +说明的主题将会被提交到永久的源代码改动日志里，因此对那些早已经不记得和 +这个补丁相关的讨论细节的有能力的读者来说，是有意义的。 + +"---" 标记行对于补丁处理工具要找到哪里是改动日志信息的结束，是不可缺少 +的。 + +对于 "---" 标记之后的额外注解，一个好的用途就是用来写 diffstat，用来显 +示修改了什么文件和每个文件都增加和删除了多少行。diffstat 对于比较大的补 +丁特别有用。其余那些只是和时刻或者开发者相关的注解，不合适放到永久的改 +动日志里的，也应该放这里。 +使用 diffstat的选项 "-p 1 -w 70" 这样文件名就会从内核源代码树的目录开始 +，不会占用太宽的空间（很容易适合80列的宽度，也许会有一些缩进。） + +在后面的参考资料中能看到适当的补丁格式的更多细节。 + +------------------------------- +第二节 提示，建议和诀窍 +------------------------------- + +本节包含很多和提交到内核的代码有关的通常的"规则"。事情永远有例外...但是 +你必须真的有好的理由这样做。你可以把本节叫做Linus的计算机科学入门课。 + +1) 读 Document/CodingStyle + +Nuff 说过，如果你的代码和这个偏离太多，那么它有可能会被拒绝，没有更多的 +审查，没有更多的评价。 + +2) #ifdef 是丑陋的 +混杂了 ifdef 的代码难以阅读和维护。别这样做。作为替代，将你的 ifdef 放 +在头文件里，有条件地定义 "static inline" 函数，或者宏，在代码里用这些东 +西。让编译器把那些"空操作"优化掉。 + +一个简单的例子，不好的代码： + + dev = alloc_etherdev (sizeof(struct funky_private)); + if (!dev) + return -ENODEV; + #ifdef CONFIG_NET_FUNKINESS + init_funky_net(dev); + #endif + +清理后的例子: + +(头文件里) + #ifndef CONFIG_NET_FUNKINESS + static inline void init_funky_net (struct net_device *d) {} + #endif + +(代码文件里) + dev = alloc_etherdev (sizeof(struct funky_private)); + if (!dev) + return -ENODEV; + init_funky_net(dev); + +3) 'static inline' 比宏好 + +Static inline 函数相比宏来说，是好得多的选择。Static inline 函数提供了 +类型安全，没有长度限制，没有格式限制，在 gcc 下开销和宏一样小。 + +宏只在 static inline 函数不是最优的时候[在 fast paths 里有很少的独立的 +案例]，或者不可能用 static inline 函数的时候[例如字符串分配]。 +应该用 'static inline' 而不是 'static __inline__', 'extern inline' 和 +'extern __inline__' 。 + +4) 不要过度设计 + +不要试图预计模糊的未来事情，这些事情也许有用也许没有用："让事情尽可能的 +简单，而不是更简单"。 + +---------------- +第三节 参考文献 +---------------- + +Andrew Morton, "The perfect patch" (tpp). + <http://www.zip.com.au/~akpm/linux/patches/stuff/tpp.txt> + +Jeff Garzik, "Linux kernel patch submission format". + <http://linux.yyz.us/patch-format.html> + +Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer". + <http://www.kroah.com/log/2005/03/31/> + <http://www.kroah.com/log/2005/07/08/> + <http://www.kroah.com/log/2005/10/19/> + <http://www.kroah.com/log/2006/01/11/> + +NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people! + <http://marc.theaimsgroup.com/?l=linux-kernel&m=112112749912944&w=2> + +Kernel Documentation/CodingStyle: + <http://sosdg.org/~coywolf/lxr/source/Documentation/CodingStyle> + +Linus Torvalds's mail on the canonical patch format: + <http://lkml.org/lkml/2005/4/7/183> +-- diff --git a/Documentation/zh_CN/oops-tracing.txt b/Documentation/zh_CN/oops-tracing.txt new file mode 100644 index 00000000000..9312608ffb8 --- /dev/null +++ b/Documentation/zh_CN/oops-tracing.txt @@ -0,0 +1,212 @@ +Chinese translated version of Documentation/oops-tracing.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: Dave Young <hidave.darkstar@gmail.com> +--------------------------------------------------------------------- +Documentation/oops-tracing.txt 的中文翻译 + +如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 +交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 +译存在问题，请联系中文版维护者。 + +中文版维护者： 杨瑞 Dave Young <hidave.darkstar@gmail.com> +中文版翻译者： 杨瑞 Dave Young <hidave.darkstar@gmail.com> +中文版校译者： 李阳 Li Yang <leo@zh-kernel.org> + 王聪 Wang Cong <xiyou.wangcong@gmail.com> + +以下为正文 +--------------------------------------------------------------------- + +注意： ksymoops 在2.6中是没有用的。 请以原有格式使用Oops(来自dmesg，等等)。 +忽略任何这样那样关于“解码Oops”或者“通过ksymoops运行”的文档。 如果你贴出运行过 +ksymoops的来自2.6的Oops，人们只会让你重贴一次。 + +快速总结 +------------- + +发现Oops并发送给看似相关的内核领域的维护者。别太担心对不上号。如果你不确定就发给 +和你所做的事情相关的代码的负责人。 如果可重现试着描述怎样重构。 那甚至比oops更有 +价值。 + +如果你对于发送给谁一无所知， 发给linux-kernel@vger.kernel.org。感谢你帮助Linux +尽可能地稳定。 + +Oops在哪里? +---------------------- + +通常Oops文本由klogd从内核缓冲区里读取并传给syslogd，由syslogd写到syslog文件中， +典型地是/var/log/messages(依赖于/etc/syslog.conf)。有时klogd崩溃了,这种情况下你 +能够运行dmesg > file来从内核缓冲区中读取数据并保存下来。 否则你可以 +cat /proc/kmsg > file， 然而你必须介入中止传输， kmsg是一个“永不结束的文件”。如 +果机器崩溃坏到你不能输入命令或者磁盘不可用那么你有三种选择:- + +（1） 手抄屏幕上的文本待机器重启后再输入计算机。 麻烦但如果没有针对崩溃的准备， +这是仅有的选择。 另外，你可以用数码相机把屏幕拍下来-不太好，但比没有强。 如果信 +息滚动到了终端的上面，你会发现以高分辩率启动（比如，vga=791）会让你读到更多的文 +本。（注意：这需要vesafb，所以对‘早期’的oops没有帮助） + +（2）用串口终端启动（请参看Documentation/serial-console.txt），运行一个null +modem到另一台机器并用你喜欢的通讯工具获取输出。Minicom工作地很好。 + +（3）使用Kdump（请参看Documentation/kdump/kdump.txt）， +使用在Documentation/kdump/gdbmacros.txt中定义的dmesg gdb宏，从旧的内存中提取内核 +环形缓冲区。 + +完整信息 +---------------- + +注意：以下来自于Linus的邮件适用于2.4内核。 我因为历史原因保留了它，并且因为其中 +一些信息仍然适用。 特别注意的是，请忽略任何ksymoops的引用。 + +From: Linus Torvalds <torvalds@osdl.org> + +怎样跟踪Oops.. [原发到linux-kernel的一封邮件] + +主要的窍门是有五年和这些烦人的oops消息打交道的经验;-) + +实际上，你有办法使它更简单。我有两个不同的方法： + + gdb /usr/src/linux/vmlinux + gdb> disassemble <offending_function> + +那是发现问题的简单办法，至少如果bug报告做的好的情况下（象这个一样-运行ksymoops +得到oops发生的函数及函数内的偏移）。 + +哦，如果报告发生的内核以相同的编译器和相似的配置编译它会有帮助的。 + +另一件要做的事是反汇编bug报告的“Code”部分：ksymoops也会用正确的工具来做这件事， +但如果没有那些工具你可以写一个傻程序： + + char str[] = "\xXX\xXX\xXX..."; + main(){} + +并用gcc -g编译它然后执行“disassemble str”（XX部分是由Oops报告的值-你可以仅剪切 +粘贴并用“\x”替换空格-我就是这么做的，因为我懒得写程序自动做这一切）。 + +另外，你可以用scripts/decodecode这个shell脚本。它的使用方法是： +decodecode < oops.txt + +“Code”之后的十六进制字节可能（在某些架构上）有一些当前指令之前的指令字节以及 +当前和之后的指令字节 + +Code: f9 0f 8d f9 00 00 00 8d 42 0c e8 dd 26 11 c7 a1 60 ea 2b f9 8b 50 08 a1 +64 ea 2b f9 8d 34 82 8b 1e 85 db 74 6d 8b 15 60 ea 2b f9 <8b> 43 04 39 42 54 +7e 04 40 89 42 54 8b 43 04 3b 05 00 f6 52 c0 + +最后，如果你想知道代码来自哪里，你可以： + + cd /usr/src/linux + make fs/buffer.s # 或任何产生BUG的文件 + +然后你会比gdb反汇编更清楚的知道发生了什么。 + +现在，问题是把你所拥有的所有数据结合起来：C源码（关于它应该怎样的一般知识）， +汇编代码及其反汇编得到的代码（另外还有从“oops”消息得到的寄存器状态-对了解毁坏的 +指针有用，而且当你有了汇编代码你也能拿其它的寄存器和任何它们对应的C表达式做匹配 +）。 + +实际上，你仅需看看哪里不匹配（这个例子是“Code”反汇编和编译器生成的代码不匹配）。 +然后你须要找出为什么不匹配。通常很简单-你看到代码使用了空指针然后你看代码想知道 +空指针是怎么出现的，还有检查它是否合法.. + +现在，如果明白这是一项耗时的工作而且需要一丁点儿的专心，没错。这就是我为什么大多 +只是忽略那些没有符号表信息的崩溃报告的原因：简单的说太难查找了（我有一些 +程序用于在内核代码段中搜索特定的模式，而且有时我也已经能找出那些崩溃的地方，但是 +仅仅是找出正确的序列也确实需要相当扎实的内核知识） + +_有时_会发生这种情况，我仅看到崩溃中的反汇编代码序列， 然后我马上就明白问题出在 +哪里。这时我才意识到自己干这个工作已经太长时间了;-) + + Linus + + +--------------------------------------------------------------------------- +关于Oops跟踪的注解： + +为了帮助Linus和其它内核开发者，klogd纳入了大量的支持来处理保护错误。为了拥有对 +地址解析的完整支持至少应该使用1.3-pl3的sysklogd包。 + +当保护错误发生时，klogd守护进程自动把内核日志信息中的重要地址翻译成它们相应的符 +号。 + +klogd执行两种类型的地址解析。首先是静态翻译其次是动态翻译。静态翻译和ksymoops +一样使用System.map文件。为了做静态翻译klogd守护进程必须在初始化时能找到system +map文件。关于klogd怎样搜索map文件请参看klogd手册页。 + +动态地址翻译在使用内核可装载模块时很重要。 因为内核模块的内存是从内核动态内存池 +里分配的，所以不管是模块开始位置还是模块中函数和符号的位置都不是固定的。 + +内核支持允许程序决定装载哪些模块和它们在内存中位置的系统调用。使用这些系统调用 +klogd守护进程生成一张符号表用于调试发生在可装载模块中的保护错误。 + +至少klogd会提供产生保护错误的模块名。还可有额外的符号信息供可装载模块开发者选择 +以从模块中输出符号信息。 + +因为内核模块环境可能是动态的，所以必须有一种机制当模块环境发生改变时来通知klogd +守护进程。 有一些可用的命令行选项允许klogd向当前执行中的守护进程发送信号，告知符 +号信息应该被刷新了。 更多信息请参看klogd手册页。 + +sysklogd发布时包含一个补丁修改了modules-2.0.0包，无论何时一个模块装载或者卸载都 +会自动向klogd发送信号。打上这个补丁提供了必要的对调试发生于内核可装载模块的保护 +错误的无缝支持。 + +以下是被klogd处理过的发生在可装载模块中的一个保护错误例子： +--------------------------------------------------------------------------- +Aug 29 09:51:01 blizard kernel: Unable to handle kernel paging request at virtual address f15e97cc +Aug 29 09:51:01 blizard kernel: current->tss.cr3 = 0062d000, %cr3 = 0062d000 +Aug 29 09:51:01 blizard kernel: *pde = 00000000 +Aug 29 09:51:01 blizard kernel: Oops: 0002 +Aug 29 09:51:01 blizard kernel: CPU: 0 +Aug 29 09:51:01 blizard kernel: EIP: 0010:[oops:_oops+16/3868] +Aug 29 09:51:01 blizard kernel: EFLAGS: 00010212 +Aug 29 09:51:01 blizard kernel: eax: 315e97cc ebx: 003a6f80 ecx: 001be77b edx: 00237c0c +Aug 29 09:51:01 blizard kernel: esi: 00000000 edi: bffffdb3 ebp: 00589f90 esp: 00589f8c +Aug 29 09:51:01 blizard kernel: ds: 0018 es: 0018 fs: 002b gs: 002b ss: 0018 +Aug 29 09:51:01 blizard kernel: Process oops_test (pid: 3374, process nr: 21, stackpage=00589000) +Aug 29 09:51:01 blizard kernel: Stack: 315e97cc 00589f98 0100b0b4 bffffed4 0012e38e 00240c64 003a6f80 00000001 +Aug 29 09:51:01 blizard kernel: 00000000 00237810 bfffff00 0010a7fa 00000003 00000001 00000000 bfffff00 +Aug 29 09:51:01 blizard kernel: bffffdb3 bffffed4 ffffffda 0000002b 0007002b 0000002b 0000002b 00000036 +Aug 29 09:51:01 blizard kernel: Call Trace: [oops:_oops_ioctl+48/80] [_sys_ioctl+254/272] [_system_call+82/128] +Aug 29 09:51:01 blizard kernel: Code: c7 00 05 00 00 00 eb 08 90 90 90 90 90 90 90 90 89 ec 5d c3 +--------------------------------------------------------------------------- + +Dr. G.W. Wettstein Oncology Research Div. Computing Facility +Roger Maris Cancer Center INTERNET: greg@wind.rmcc.com +820 4th St. N. +Fargo, ND 58122 +Phone: 701-234-7556 + + +--------------------------------------------------------------------------- +受污染的内核 + +一些oops报告在程序记数器之后包含字符串'Tainted: '。这表明内核已经被一些东西给污 +染了。 该字符串之后紧跟着一系列的位置敏感的字符，每个代表一个特定的污染值。 + + 1：'G'如果所有装载的模块都有GPL或相容的许可证，'P'如果装载了任何的专有模块。 +没有模块MODULE_LICENSE或者带有insmod认为是与GPL不相容的的MODULE_LICENSE的模块被 +认定是专有的。 + + 2：'F'如果有任何通过“insmod -f”被强制装载的模块，' '如果所有模块都被正常装载。 + + 3：'S'如果oops发生在SMP内核中，运行于没有证明安全运行多处理器的硬件。 当前这种 +情况仅限于几种不支持SMP的速龙处理器。 + + 4：'R'如果模块通过“insmod -f”被强制装载，' '如果所有模块都被正常装载。 + + 5：'M'如果任何处理器报告了机器检查异常，' '如果没有发生机器检查异常。 + + 6：'B'如果页释放函数发现了一个错误的页引用或者一些非预期的页标志。 + + 7：'U'如果用户或者用户应用程序特别请求设置污染标志，否则' '。 + + 8：'D'如果内核刚刚死掉，比如有OOPS或者BUG。 + +使用'Tainted: '字符串的主要原因是要告诉内核调试者，这是否是一个干净的内核亦或发 +生了任何的不正常的事。污染是永久的：即使出错的模块已经被卸载了，污染值仍然存在， +以表明内核不再值得信任。 diff --git a/Documentation/zh_CN/sparse.txt b/Documentation/zh_CN/sparse.txt new file mode 100644 index 00000000000..75992a603ae --- /dev/null +++ b/Documentation/zh_CN/sparse.txt @@ -0,0 +1,100 @@ +Chinese translated version of Documentation/sparse.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: Li Yang <leo@zh-kernel.org> +--------------------------------------------------------------------- +Documentation/sparse.txt 的中文翻译 + +如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 +交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 +译存在问题，请联系中文版维护者。 + +中文版维护者： 李阳 Li Yang <leo@zh-kernel.org> +中文版翻译者： 李阳 Li Yang <leo@zh-kernel.org> + + +以下为正文 +--------------------------------------------------------------------- + +Copyright 2004 Linus Torvalds +Copyright 2004 Pavel Machek <pavel@suse.cz> +Copyright 2006 Bob Copeland <me@bobcopeland.com> + +使用 sparse 工具做类型检查 +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +"__bitwise" 是一种类型属性，所以你应该这样使用它： + + typedef int __bitwise pm_request_t; + + enum pm_request { + PM_SUSPEND = (__force pm_request_t) 1, + PM_RESUME = (__force pm_request_t) 2 + }; + +这样会使 PM_SUSPEND 和 PM_RESUME 成为位方式(bitwise)整数（使用"__force" +是因为 sparse 会抱怨改变位方式的类型转换，但是这里我们确实需要强制进行转 +换）。而且因为所有枚举值都使用了相同的类型，这里的"enum pm_request"也将 +会使用那个类型做为底层实现。 + +而且使用 gcc 编译的时候，所有的 __bitwise/__force 都会消失，最后在 gcc +看来它们只不过是普通的整数。 + +坦白来说，你并不需要使用枚举类型。上面那些实际都可以浓缩成一个特殊的"int +__bitwise"类型。 + +所以更简单的办法只要这样做： + + typedef int __bitwise pm_request_t; + + #define PM_SUSPEND ((__force pm_request_t) 1) + #define PM_RESUME ((__force pm_request_t) 2) + +现在你就有了严格的类型检查所需要的所有基础架构。 + +一个小提醒：常数整数"0"是特殊的。你可以直接把常数零当作位方式整数使用而 +不用担心 sparse 会抱怨。这是因为"bitwise"（恰如其名）是用来确保不同位方 +式类型不会被弄混（小尾模式，大尾模式，cpu尾模式，或者其他），对他们来说 +常数"0"确实是特殊的。 + +获取 sparse 工具 +~~~~~~~~~~~~~~~~ + +你可以从 Sparse 的主页获取最新的发布版本： + + http://www.kernel.org/pub/linux/kernel/people/josh/sparse/ + +或者，你也可以使用 git 克隆最新的 sparse 开发版本： + + git://git.kernel.org/pub/scm/linux/kernel/git/josh/sparse.git + +DaveJ 把每小时自动生成的 git 源码树 tar 包放在以下地址： + + http://www.codemonkey.org.uk/projects/git-snapshots/sparse/ + +一旦你下载了源码，只要以普通用户身份运行： + + make + make install + +它将会被自动安装到你的 ~/bin 目录下。 + +使用 sparse 工具 +~~~~~~~~~~~~~~~~ + +用"make C=1"命令来编译内核，会对所有重新编译的 C 文件使用 sparse 工具。 +或者使用"make C=2"命令，无论文件是否被重新编译都会对其使用 sparse 工具。 +如果你已经编译了内核，用后一种方式可以很快地检查整个源码树。 + +make 的可选变量 CHECKFLAGS 可以用来向 sparse 工具传递参数。编译系统会自 +动向 sparse 工具传递 -Wbitwise 参数。你可以定义 __CHECK_ENDIAN__ 来进行 +大小尾检查。 + + make C=2 CHECKFLAGS="-D__CHECK_ENDIAN__" + +这些检查默认都是被关闭的，因为他们通常会产生大量的警告。 diff --git a/Documentation/zh_CN/stable_kernel_rules.txt b/Documentation/zh_CN/stable_kernel_rules.txt new file mode 100644 index 00000000000..b5b9b0ab02f --- /dev/null +++ b/Documentation/zh_CN/stable_kernel_rules.txt @@ -0,0 +1,66 @@ +Chinese translated version of Documentation/stable_kernel_rules.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: TripleX Chung <triplex@zh-kernel.org> +--------------------------------------------------------------------- +Documentation/stable_kernel_rules.txt 的中文翻译 + +如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 +交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 +译存在问题，请联系中文版维护者。 + + +中文版维护者： 钟宇 TripleX Chung <triplex@zh-kernel.org> +中文版翻译者： 钟宇 TripleX Chung <triplex@zh-kernel.org> +中文版校译者： 李阳 Li Yang <leo@zh-kernel.org> + Kangkai Yin <e12051@motorola.com> + +以下为正文 +--------------------------------------------------------------------- + +关于Linux 2.6稳定版发布，所有你想知道的事情。 + +关于哪些类型的补丁可以被接收进入稳定版代码树，哪些不可以的规则： + + - 必须是显而易见的正确，并且经过测试的。 + - 连同上下文，不能大于100行。 + - 必须只修正一件事情。 + - 必须修正了一个给大家带来麻烦的真正的bug（不是“这也许是一个问题...” + 那样的东西）。 + - 必须修正带来如下后果的问题：编译错误（对被标记为CONFIG_BROKEN的例外）， + 内核崩溃，挂起，数据损坏，真正的安全问题，或者一些类似“哦，这不 + 好”的问题。简短的说，就是一些致命的问题。 + - 没有“理论上的竞争条件”，除非能给出竞争条件如何被利用的解释。 + - 不能存在任何的“琐碎的”修正（拼写修正，去掉多余空格之类的）。 + - 必须被相关子系统的维护者接受。 + - 必须遵循Documentation/SubmittingPatches里的规则。 + +向稳定版代码树提交补丁的过程： + + - 在确认了补丁符合以上的规则后，将补丁发送到stable@kernel.org。 + - 如果补丁被接受到队列里，发送者会收到一个ACK回复，如果没有被接受，收 + 到的是NAK回复。回复需要几天的时间，这取决于开发者的时间安排。 + - 被接受的补丁会被加到稳定版本队列里，等待其他开发者的审查。 + - 安全方面的补丁不要发到这个列表，应该发送到security@kernel.org。 + +审查周期： + + - 当稳定版的维护者决定开始一个审查周期，补丁将被发送到审查委员会，以 + 及被补丁影响的领域的维护者（除非提交者就是该领域的维护者）并且抄送 + 到linux-kernel邮件列表。 + - 审查委员会有48小时的时间，用来决定给该补丁回复ACK还是NAK。 + - 如果委员会中有成员拒绝这个补丁，或者linux-kernel列表上有人反对这个 + 补丁，并提出维护者和审查委员会之前没有意识到的问题，补丁会从队列中 + 丢弃。 + - 在审查周期结束的时候，那些得到ACK回应的补丁将会被加入到最新的稳定版 + 发布中，一个新的稳定版发布就此产生。 + - 安全性补丁将从内核安全小组那里直接接收到稳定版代码树中，而不是通过 + 通常的审查周期。请联系内核安全小组以获得关于这个过程的更多细节。 + +审查委员会： + - 由一些自愿承担这项任务的内核开发者，和几个非志愿的组成。 diff --git a/Documentation/zh_CN/volatile-considered-harmful.txt b/Documentation/zh_CN/volatile-considered-harmful.txt new file mode 100644 index 00000000000..ba8149d2233 --- /dev/null +++ b/Documentation/zh_CN/volatile-considered-harmful.txt @@ -0,0 +1,113 @@ +Chinese translated version of Documentation/volatile-considered-harmful.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. + +Maintainer: Jonathan Corbet <corbet@lwn.net> +Chinese maintainer: Bryan Wu <bryan.wu@analog.com> +--------------------------------------------------------------------- +Documentation/volatile-considered-harmful.txt 的中文翻译 + +如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 +交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 +译存在问题，请联系中文版维护者。 + +英文版维护者： Jonathan Corbet <corbet@lwn.net> +中文版维护者： 伍鹏 Bryan Wu <bryan.wu@analog.com> +中文版翻译者： 伍鹏 Bryan Wu <bryan.wu@analog.com> +中文版校译者： 张汉辉 Eugene Teo <eugeneteo@kernel.sg> + 杨瑞 Dave Young <hidave.darkstar@gmail.com> +以下为正文 +--------------------------------------------------------------------- + +为什么不应该使用“volatile”类型 +------------------------------ + +C程序员通常认为volatile表示某个变量可以在当前执行的线程之外被改变；因此，在内核 +中用到共享数据结构时，常常会有C程序员喜欢使用volatile这类变量。换句话说，他们经 +常会把volatile类型看成某种简易的原子变量，当然它们不是。在内核中使用volatile几 +乎总是错误的；本文档将解释为什么这样。 + +理解volatile的关键是知道它的目的是用来消除优化，实际上很少有人真正需要这样的应 +用。在内核中，程序员必须防止意外的并发访问破坏共享的数据结构，这其实是一个完全 +不同的任务。用来防止意外并发访问的保护措施，可以更加高效的避免大多数优化相关的 +问题。 + +像volatile一样，内核提供了很多原语来保证并发访问时的数据安全（自旋锁, 互斥量,内 +存屏障等等），同样可以防止意外的优化。如果可以正确使用这些内核原语，那么就没有 +必要再使用volatile。如果仍然必须使用volatile，那么几乎可以肯定在代码的某处有一 +个bug。在正确设计的内核代码中，volatile能带来的仅仅是使事情变慢。 + +思考一下这段典型的内核代码： + + spin_lock(&the_lock); + do_something_on(&shared_data); + do_something_else_with(&shared_data); + spin_unlock(&the_lock); + +如果所有的代码都遵循加锁规则，当持有the_lock的时候，不可能意外的改变shared_data的 +值。任何可能访问该数据的其他代码都会在这个锁上等待。自旋锁原语跟内存屏障一样—— 它 +们显式的用来书写成这样 —— 意味着数据访问不会跨越它们而被优化。所以本来编译器认为 +它知道在shared_data里面将有什么，但是因为spin_lock()调用跟内存屏障一样，会强制编 +译器忘记它所知道的一切。那么在访问这些数据时不会有优化的问题。 + +如果shared_data被声名为volatile，锁操作将仍然是必须的。就算我们知道没有其他人正在 +使用它，编译器也将被阻止优化对临界区内shared_data的访问。在锁有效的同时， +shared_data不是volatile的。在处理共享数据的时候，适当的锁操作可以不再需要 +volatile —— 并且是有潜在危害的。 + +volatile的存储类型最初是为那些内存映射的I/O寄存器而定义。在内核里，寄存器访问也应 +该被锁保护，但是人们也不希望编译器“优化”临界区内的寄存器访问。内核里I/O的内存访问 +是通过访问函数完成的；不赞成通过指针对I/O内存的直接访问，并且不是在所有体系架构上 +都能工作。那些访问函数正是为了防止意外优化而写的，因此，再说一次，volatile类型不 +是必需的。 + +另一种引起用户可能使用volatile的情况是当处理器正忙着等待一个变量的值。正确执行一 +个忙等待的方法是： + + while (my_variable != what_i_want) + cpu_relax(); + +cpu_relax()调用会降低CPU的能量消耗或者让位于超线程双处理器；它也作为内存屏障一样出 +现，所以，再一次，volatile不是必需的。当然，忙等待一开始就是一种反常规的做法。 + +在内核中，一些稀少的情况下volatile仍然是有意义的： + + - 在一些体系架构的系统上，允许直接的I/0内存访问，那么前面提到的访问函数可以使用 + volatile。基本上，每一个访问函数调用它自己都是一个小的临界区域并且保证了按照 + 程序员期望的那样发生访问操作。 + + - 某些会改变内存的内联汇编代码虽然没有什么其他明显的附作用，但是有被GCC删除的可 + 能性。在汇编声明中加上volatile关键字可以防止这种删除操作。 + + - Jiffies变量是一种特殊情况，虽然每次引用它的时候都可以有不同的值，但读jiffies + 变量时不需要任何特殊的加锁保护。所以jiffies变量可以使用volatile，但是不赞成 + 其他跟jiffies相同类型变量使用volatile。Jiffies被认为是一种“愚蠢的遗留物" + （Linus的话）因为解决这个问题比保持现状要麻烦的多。 + + - 由于某些I/0设备可能会修改连续一致的内存,所以有时,指向连续一致内存的数据结构 + 的指针需要正确的使用volatile。网络适配器使用的环状缓存区正是这类情形的一个例 + 子，其中适配器用改变指针来表示哪些描述符已经处理过了。 + +对于大多代码，上述几种可以使用volatile的情况都不适用。所以，使用volatile是一种 +bug并且需要对这样的代码额外仔细检查。那些试图使用volatile的开发人员需要退一步想想 +他们真正想实现的是什么。 + +非常欢迎删除volatile变量的补丁 － 只要证明这些补丁完整的考虑了并发问题。 + +注释 +---- + +[1] http://lwn.net/Articles/233481/ +[2] http://lwn.net/Articles/233482/ + +致谢 +---- + +最初由Randy Dunlap推动并作初步研究 +由Jonathan Corbet撰写 +参考Satyam Sharma，Johannes Stezenbach，Jesper Juhl，Heikki Orsila， +H. Peter Anvin，Philipp Hahn和Stefan Richter的意见改善了本档。 |