Re: [PATCH v4] Documentation:sh:convert register-banks.txt and new-machine.txt to rst format.

From: Vandana BN
Date: Sat Jun 29 2019 - 12:20:13 EST

Next message: Guenter Roeck: "Re: [PATCH v4 3/3] fpga: dfl: fme: add power management support"
Previous message: Andy Shevchenko: "Re: [PATCH 10/10] tools/power/x86: A tool to validate Intel Speed Select commands"
In reply to: Mauro Carvalho Chehab: "Re: [PATCH v4] Documentation:sh:convert register-banks.txt and new-machine.txt to rst format."
Next in thread: Vandana BN: "[PATCH v5] Documentation:sh:convert register-banks.txt and new-machine.txt to rst format."
Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]

On 29/06/19 9:32 PM, Mauro Carvalho Chehab wrote:
> Em Sat, 29 Jun 2019 21:26:29 +0530
> Vandana BN <bnvandana@xxxxxxxxx> escreveu:
>
>> On 29/06/19 8:20 PM, Mauro Carvalho Chehab wrote:
>>> Em Sat, 29 Jun 2019 20:02:45 +0530
>>> Vandana BN <bnvandana@xxxxxxxxx> escreveu:
>>>
>>>> This patch converts new-machine.txt and register-banks.txt
>>>> to ReST format, No content change.
>>>> Added interfaces.rst to contain kernel-doc markups from index.rst
>>>> Added interfaces.rst,new-machine.rst and register-banks.rst to sh/index.rst
>>>> Added SPDX tag in index.rst
>>>>
>>>> Signed-off-by: Vandana BN <bnvandana@xxxxxxxxx>
>>> Looks good to me. Just a final thing to do.
>>>
>>> Be sure to run:
>>>
>>> ./scripts/documentation-file-ref-check
>>>
>>> in order to check that you're not breaking any references to the file.
>>> If it breaks, please adjust the reference to reflect the file
>>> rename.
>>>
>>> After fixing the broken reference, feel free do add:
>>>
>>> Reviewed-by: Mauro Carvalho Chehab <mchehab@xxxxxxxxxx>
>> Thanks Mauro,
>>
>> i don't not see any broken references.
> Then maybe the script is broken. A simple grep here (linux-next) shows
> one such reference:
>
> git grep Documentation/sh/
> MAINTAINERS:F: Documentation/sh/
> arch/sh/Kconfig.cpu: See <file:Documentation/sh/register-banks.txt> for further
>
Oh ok, yes i see it now..

Will fix and send a patch.

>>>> ---
>>>> Documentation/sh/index.rst | 65 +------
>>>> Documentation/sh/interface.rst | 59 ++++++
>>>> .../sh/{new-machine.txt => new-machine.rst} | 171 +++++++++---------
>>>> ...{register-banks.txt => register-banks.rst} | 8 +-
>>>> 4 files changed, 163 insertions(+), 140 deletions(-)
>>>> create mode 100644 Documentation/sh/interface.rst
>>>> rename Documentation/sh/{new-machine.txt => new-machine.rst} (79%)
>>>> rename Documentation/sh/{register-banks.txt => register-banks.rst} (90%)
>>>>
>>>> diff --git a/Documentation/sh/index.rst b/Documentation/sh/index.rst
>>>> index bc8db7ba894a..fec3c405b6b9 100644
>>>> --- a/Documentation/sh/index.rst
>>>> +++ b/Documentation/sh/index.rst
>>>> @@ -1,59 +1,14 @@
>>>> -=======================
>>>> -SuperH Interfaces Guide
>>>> -=======================
>>>> +.. SPDX-License-Identifier: GPL-2.0
>>>>
>>>> -:Author: Paul Mundt
>>>> -
>>>> -Memory Management
>>>> -=================
>>>> -
>>>> -SH-4
>>>> -----
>>>> -
>>>> -Store Queue API
>>>> -~~~~~~~~~~~~~~~
>>>> -
>>>> -.. kernel-doc:: arch/sh/kernel/cpu/sh4/sq.c
>>>> - :export:
>>>> -
>>>> -SH-5
>>>> -----
>>>> -
>>>> -TLB Interfaces
>>>> -~~~~~~~~~~~~~~
>>>> -
>>>> -.. kernel-doc:: arch/sh/mm/tlb-sh5.c
>>>> - :internal:
>>>> -
>>>> -.. kernel-doc:: arch/sh/include/asm/tlb_64.h
>>>> - :internal:
>>>> +====================
>>>> +SuperH Documentation
>>>> +====================
>>>>
>>>> -Machine Specific Interfaces
>>>> -===========================
>>>> -
>>>> -mach-dreamcast
>>>> ---------------
>>>> -
>>>> -.. kernel-doc:: arch/sh/boards/mach-dreamcast/rtc.c
>>>> - :internal:
>>>> -
>>>> -mach-x3proto
>>>> -------------
>>>> -
>>>> -.. kernel-doc:: arch/sh/boards/mach-x3proto/ilsel.c
>>>> - :export:
>>>> -
>>>> -Busses
>>>> -======
>>>> -
>>>> -SuperHyway
>>>> -----------
>>>> -
>>>> -.. kernel-doc:: drivers/sh/superhyway/superhyway.c
>>>> - :export:
>>>> +:Author: Paul Mundt
>>>>
>>>> -Maple
>>>> ------
>>>> +.. toctree::
>>>> + :maxdepth: 2
>>>>
>>>> -.. kernel-doc:: drivers/sh/maple/maple.c
>>>> - :export:
>>>> + interface
>>>> + new-machine
>>>> + register-banks
>>>> diff --git a/Documentation/sh/interface.rst b/Documentation/sh/interface.rst
>>>> new file mode 100644
>>>> index 000000000000..bc8db7ba894a
>>>> --- /dev/null
>>>> +++ b/Documentation/sh/interface.rst
>>>> @@ -0,0 +1,59 @@
>>>> +=======================
>>>> +SuperH Interfaces Guide
>>>> +=======================
>>>> +
>>>> +:Author: Paul Mundt
>>>> +
>>>> +Memory Management
>>>> +=================
>>>> +
>>>> +SH-4
>>>> +----
>>>> +
>>>> +Store Queue API
>>>> +~~~~~~~~~~~~~~~
>>>> +
>>>> +.. kernel-doc:: arch/sh/kernel/cpu/sh4/sq.c
>>>> + :export:
>>>> +
>>>> +SH-5
>>>> +----
>>>> +
>>>> +TLB Interfaces
>>>> +~~~~~~~~~~~~~~
>>>> +
>>>> +.. kernel-doc:: arch/sh/mm/tlb-sh5.c
>>>> + :internal:
>>>> +
>>>> +.. kernel-doc:: arch/sh/include/asm/tlb_64.h
>>>> + :internal:
>>>> +
>>>> +Machine Specific Interfaces
>>>> +===========================
>>>> +
>>>> +mach-dreamcast
>>>> +--------------
>>>> +
>>>> +.. kernel-doc:: arch/sh/boards/mach-dreamcast/rtc.c
>>>> + :internal:
>>>> +
>>>> +mach-x3proto
>>>> +------------
>>>> +
>>>> +.. kernel-doc:: arch/sh/boards/mach-x3proto/ilsel.c
>>>> + :export:
>>>> +
>>>> +Busses
>>>> +======
>>>> +
>>>> +SuperHyway
>>>> +----------
>>>> +
>>>> +.. kernel-doc:: drivers/sh/superhyway/superhyway.c
>>>> + :export:
>>>> +
>>>> +Maple
>>>> +-----
>>>> +
>>>> +.. kernel-doc:: drivers/sh/maple/maple.c
>>>> + :export:
>>>> diff --git a/Documentation/sh/new-machine.txt b/Documentation/sh/new-machine.rst
>>>> similarity index 79%
>>>> rename from Documentation/sh/new-machine.txt
>>>> rename to Documentation/sh/new-machine.rst
>>>> index e0961a66130b..b16c33342642 100644
>>>> --- a/Documentation/sh/new-machine.txt
>>>> +++ b/Documentation/sh/new-machine.rst
>>>> @@ -1,8 +1,8 @@
>>>> +================================
>>>> +Adding a new board to LinuxSH
>>>> +================================
>>>>
>>>> - Adding a new board to LinuxSH
>>>> - ================================
>>>> -
>>>> - Paul Mundt <lethal@xxxxxxxxxxxx>
>>>> +Paul Mundt <lethal@xxxxxxxxxxxx>
>>>>
>>>> This document attempts to outline what steps are necessary to add support
>>>> for new boards to the LinuxSH port under the new 2.5 and 2.6 kernels. This
>>>> @@ -19,65 +19,67 @@ include/asm-sh/. For the new kernel, things are broken out by board type,
>>>> companion chip type, and CPU type. Looking at a tree view of this directory
>>>> hierarchy looks like the following:
>>>>
>>>> -Board-specific code:
>>>> -
>>>> -.
>>>> -|-- arch
>>>> -| `-- sh
>>>> -| `-- boards
>>>> -| |-- adx
>>>> -| | `-- board-specific files
>>>> -| |-- bigsur
>>>> -| | `-- board-specific files
>>>> -| |
>>>> -| ... more boards here ...
>>>> -|
>>>> -`-- include
>>>> - `-- asm-sh
>>>> - |-- adx
>>>> - | `-- board-specific headers
>>>> - |-- bigsur
>>>> - | `-- board-specific headers
>>>> - |
>>>> - .. more boards here ...
>>>> -
>>>> -Next, for companion chips:
>>>> -.
>>>> -`-- arch
>>>> - `-- sh
>>>> - `-- cchips
>>>> - `-- hd6446x
>>>> - `-- hd64461
>>>> - `-- cchip-specific files
>>>> +Board-specific code::
>>>> +
>>>> + .
>>>> + |-- arch
>>>> + | `-- sh
>>>> + | `-- boards
>>>> + | |-- adx
>>>> + | | `-- board-specific files
>>>> + | |-- bigsur
>>>> + | | `-- board-specific files
>>>> + | |
>>>> + | ... more boards here ...
>>>> + |
>>>> + `-- include
>>>> + `-- asm-sh
>>>> + |-- adx
>>>> + | `-- board-specific headers
>>>> + |-- bigsur
>>>> + | `-- board-specific headers
>>>> + |
>>>> + .. more boards here ...
>>>> +
>>>> +Next, for companion chips::
>>>> +
>>>> + .
>>>> + `-- arch
>>>> + `-- sh
>>>> + `-- cchips
>>>> + `-- hd6446x
>>>> + `-- hd64461
>>>> + `-- cchip-specific files
>>>>
>>>> ... and so on. Headers for the companion chips are treated the same way as
>>>> board-specific headers. Thus, include/asm-sh/hd64461 is home to all of the
>>>> hd64461-specific headers.
>>>>
>>>> -Finally, CPU family support is also abstracted:
>>>> -.
>>>> -|-- arch
>>>> -| `-- sh
>>>> -| |-- kernel
>>>> -| | `-- cpu
>>>> -| | |-- sh2
>>>> -| | | `-- SH-2 generic files
>>>> -| | |-- sh3
>>>> -| | | `-- SH-3 generic files
>>>> -| | `-- sh4
>>>> -| | `-- SH-4 generic files
>>>> -| `-- mm
>>>> -| `-- This is also broken out per CPU family, so each family can
>>>> -| have their own set of cache/tlb functions.
>>>> -|
>>>> -`-- include
>>>> - `-- asm-sh
>>>> - |-- cpu-sh2
>>>> - | `-- SH-2 specific headers
>>>> - |-- cpu-sh3
>>>> - | `-- SH-3 specific headers
>>>> - `-- cpu-sh4
>>>> - `-- SH-4 specific headers
>>>> +Finally, CPU family support is also abstracted::
>>>> +
>>>> + .
>>>> + |-- arch
>>>> + | `-- sh
>>>> + | |-- kernel
>>>> + | | `-- cpu
>>>> + | | |-- sh2
>>>> + | | | `-- SH-2 generic files
>>>> + | | |-- sh3
>>>> + | | | `-- SH-3 generic files
>>>> + | | `-- sh4
>>>> + | | `-- SH-4 generic files
>>>> + | `-- mm
>>>> + | `-- This is also broken out per CPU family, so each family can
>>>> + | have their own set of cache/tlb functions.
>>>> + |
>>>> + `-- include
>>>> + `-- asm-sh
>>>> + |-- cpu-sh2
>>>> + | `-- SH-2 specific headers
>>>> + |-- cpu-sh3
>>>> + | `-- SH-3 specific headers
>>>> + `-- cpu-sh4
>>>> + `-- SH-4 specific headers
>>>>
>>>> It should be noted that CPU subtypes are _not_ abstracted. Thus, these still
>>>> need to be dealt with by the CPU family specific code.
>>>> @@ -112,18 +114,20 @@ setup code, we're required at the very least to provide definitions for
>>>> get_system_type() and platform_setup(). For our imaginary board, this
>>>> might look something like:
>>>>
>>>> -/*
>>>> - * arch/sh/boards/vapor/setup.c - Setup code for imaginary board
>>>> - */
>>>> -#include <linux/init.h>
>>>> +.. code-block:: c
>>>> +
>>>> + /*
>>>> + * arch/sh/boards/vapor/setup.c - Setup code for imaginary board
>>>> + */
>>>> + #include <linux/init.h>
>>>>
>>>> -const char *get_system_type(void)
>>>> -{
>>>> - return "FooTech Vaporboard";
>>>> -}
>>>> + const char *get_system_type(void)
>>>> + {
>>>> + return "FooTech Vaporboard";
>>>> + }
>>>>
>>>> -int __init platform_setup(void)
>>>> -{
>>>> + int __init platform_setup(void)
>>>> + {
>>>> /*
>>>> * If our hardware actually existed, we would do real
>>>> * setup here. Though it's also sane to leave this empty
>>>> @@ -136,7 +140,8 @@ int __init platform_setup(void)
>>>> /* And whatever else ... */
>>>>
>>>> return 0;
>>>> -}
>>>> + }
>>>> +
>>>>
>>>> Our new imaginary board will also have to tie into the machvec in order for it
>>>> to be of any use.
>>>> @@ -172,16 +177,17 @@ sufficient.
>>>> vector.
>>>>
>>>> Note that these prototypes are generated automatically by setting
>>>> - __IO_PREFIX to something sensible. A typical example would be:
>>>> + __IO_PREFIX to something sensible. A typical example would be::
>>>>
>>>> #define __IO_PREFIX vapor
>>>> #include <asm/io_generic.h>
>>>>
>>>> +
>>>> somewhere in the board-specific header. Any boards being ported that still
>>>> have a legacy io.h should remove it entirely and switch to the new model.
>>>>
>>>> - Add machine vector definitions to the board's setup.c. At a bare minimum,
>>>> - this must be defined as something like:
>>>> + this must be defined as something like::
>>>>
>>>> struct sh_machine_vector mv_vapor __initmv = {
>>>> .mv_name = "vapor",
>>>> @@ -202,11 +208,11 @@ Large portions of the build system are now entirely dynamic, and merely
>>>> require the proper entry here and there in order to get things done.
>>>>
>>>> The first thing to do is to add an entry to arch/sh/Kconfig, under the
>>>> -"System type" menu:
>>>> +"System type" menu::
>>>>
>>>> -config SH_VAPOR
>>>> - bool "Vapor"
>>>> - help
>>>> + config SH_VAPOR
>>>> + bool "Vapor"
>>>> + help
>>>> select Vapor if configuring for a FooTech Vaporboard.
>>>>
>>>> next, this has to be added into arch/sh/Makefile. All boards require a
>>>> @@ -232,6 +238,8 @@ space restating it here. After this is done, you will be able to use
>>>> implicit checks for your board if you need this somewhere throughout the
>>>> common code, such as:
>>>>
>>>> +::
>>>> +
>>>> /* Make sure we're on the FooTech Vaporboard */
>>>> if (!mach_is_vapor())
>>>> return -ENODEV;
>>>> @@ -253,12 +261,13 @@ build target, and it will be implicitly listed as such in the help text.
>>>> Looking at the 'make help' output, you should now see something like:
>>>>
>>>> Architecture specific targets (sh):
>>>> - zImage - Compressed kernel image (arch/sh/boot/zImage)
>>>> - adx_defconfig - Build for adx
>>>> - cqreek_defconfig - Build for cqreek
>>>> - dreamcast_defconfig - Build for dreamcast
>>>> -...
>>>> - vapor_defconfig - Build for vapor
>>>> +
>>>> + - zImage - Compressed kernel image (arch/sh/boot/zImage)
>>>> + - adx_defconfig - Build for adx
>>>> + - cqreek_defconfig - Build for cqreek
>>>> + - dreamcast_defconfig - Build for dreamcast
>>>> + - ...
>>>> + - vapor_defconfig - Build for vapor
>>>>
>>>> which then allows you to do:
>>>>
>>>> diff --git a/Documentation/sh/register-banks.txt b/Documentation/sh/register-banks.rst
>>>> similarity index 90%
>>>> rename from Documentation/sh/register-banks.txt
>>>> rename to Documentation/sh/register-banks.rst
>>>> index a6719f2f6594..acccfaf80355 100644
>>>> --- a/Documentation/sh/register-banks.txt
>>>> +++ b/Documentation/sh/register-banks.rst
>>>> @@ -1,8 +1,9 @@
>>>> - Notes on register bank usage in the kernel
>>>> - ==========================================
>>>> +==========================================
>>>> +Notes on register bank usage in the kernel
>>>> +==========================================
>>>>
>>>> Introduction
>>>> -------------
>>>> +============
>>>>
>>>> The SH-3 and SH-4 CPU families traditionally include a single partial register
>>>> bank (selected by SR.RB, only r0 ... r7 are banked), whereas other families
>>>> @@ -30,4 +31,3 @@ Presently the kernel uses several of these registers.
>>>> - The SR.IMASK interrupt handler makes use of this to set the
>>>> interrupt priority level (used by local_irq_enable())
>>>> - r7_bank (current)
>>>> -
>>>> --
>>>> 2.17.1
>>>>
>>>
>>> Thanks,
>>> Mauro
>> Regards,
>>
>> Vandana.
>>
>
>
> Thanks,
> Mauro

Thanks,

Vandana.

Next message: Guenter Roeck: "Re: [PATCH v4 3/3] fpga: dfl: fme: add power management support"
Previous message: Andy Shevchenko: "Re: [PATCH 10/10] tools/power/x86: A tool to validate Intel Speed Select commands"
In reply to: Mauro Carvalho Chehab: "Re: [PATCH v4] Documentation:sh:convert register-banks.txt and new-machine.txt to rst format."
Next in thread: Vandana BN: "[PATCH v5] Documentation:sh:convert register-banks.txt and new-machine.txt to rst format."
Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]