tjh.dev / kernel
Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel os linux
fork atom

ntb.txt: standardize document format

Each text file under Documentation follows a different
format. Some doesn't even have titles!

Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx.

This file is using some other markup notation (likely, markdown).
Convert it to the adopted standard:

- Adjust the header level markup;
- Adjust identation for debugfs files and module parameters.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

authored by

Mauro Carvalho Chehab and committed by
Jonathan Corbet e3866726 853afb71

+37 -18
+37 -18
Documentation/ntb.txt
··· 1 - # NTB Drivers 1 + =========== 2 + NTB Drivers 3 + =========== 2 4 3 5 NTB (Non-Transparent Bridge) is a type of PCI-Express bridge chip that connects 4 6 the separate memory systems of two computers to the same PCI-Express fabric. ··· 12 10 events. Memory windows allow translated read and write access to the peer 13 11 memory. 14 12 15 - ## NTB Core Driver (ntb) 13 + NTB Core Driver (ntb) 14 + ===================== 16 15 17 16 The NTB core driver defines an api wrapping the common feature set, and allows 18 17 clients interested in NTB features to discover NTB the devices supported by ··· 21 18 component making use of the NTB api. The term "driver," or "hardware driver," 22 19 is used here to mean a driver for a specific vendor and model of NTB hardware. 23 20 24 - ## NTB Client Drivers 21 + NTB Client Drivers 22 + ================== 25 23 26 24 NTB client drivers should register with the NTB core driver. After 27 25 registering, the client probe and remove functions will be called appropriately ··· 30 26 registration uses the Linux Device framework, so it should feel familiar to 31 27 anyone who has written a pci driver. 32 28 33 - ### NTB Transport Client (ntb\_transport) and NTB Netdev (ntb\_netdev) 29 + NTB Transport Client (ntb\_transport) and NTB Netdev (ntb\_netdev) 30 + ------------------------------------------------------------------ 34 31 35 32 The primary client for NTB is the Transport client, used in tandem with NTB 36 33 Netdev. These drivers function together to create a logical link to the peer, ··· 42 37 Transport queue pair buffer. The Transport client may be used for other things 43 38 besides Netdev, however no other applications have yet been written. 44 39 45 - ### NTB Ping Pong Test Client (ntb\_pingpong) 40 + NTB Ping Pong Test Client (ntb\_pingpong) 41 + ----------------------------------------- 46 42 47 43 The Ping Pong test client serves as a demonstration to exercise the doorbell 48 44 and scratchpad registers of NTB hardware, and as an example simple NTB client. ··· 70 64 * dyndbg - It is suggested to specify dyndbg=+p when loading this module, and 71 65 then to observe debugging output on the console. 72 66 73 - ### NTB Tool Test Client (ntb\_tool) 67 + NTB Tool Test Client (ntb\_tool) 68 + -------------------------------- 74 69 75 70 The Tool test client serves for debugging, primarily, ntb hardware and drivers. 76 71 The Tool provides access through debugfs for reading, setting, and clearing the ··· 81 74 82 75 Debugfs Files: 83 76 84 - * *debugfs*/ntb\_tool/*hw*/ - A directory in debugfs will be created for each 77 + * *debugfs*/ntb\_tool/*hw*/ 78 + A directory in debugfs will be created for each 85 79 NTB device probed by the tool. This directory is shortened to *hw* 86 80 below. 87 - * *hw*/db - This file is used to read, set, and clear the local doorbell. Not 81 + * *hw*/db 82 + This file is used to read, set, and clear the local doorbell. Not 88 83 all operations may be supported by all hardware. To read the doorbell, 89 84 read the file. To set the doorbell, write `s` followed by the bits to 90 85 set (eg: `echo 's 0x0101' > db`). To clear the doorbell, write `c` 91 86 followed by the bits to clear. 92 - * *hw*/mask - This file is used to read, set, and clear the local doorbell mask. 87 + * *hw*/mask 88 + This file is used to read, set, and clear the local doorbell mask. 93 89 See *db* for details. 94 - * *hw*/peer\_db - This file is used to read, set, and clear the peer doorbell. 90 + * *hw*/peer\_db 91 + This file is used to read, set, and clear the peer doorbell. 95 92 See *db* for details. 96 - * *hw*/peer\_mask - This file is used to read, set, and clear the peer doorbell 93 + * *hw*/peer\_mask 94 + This file is used to read, set, and clear the peer doorbell 97 95 mask. See *db* for details. 98 - * *hw*/spad - This file is used to read and write local scratchpads. To read 96 + * *hw*/spad 97 + This file is used to read and write local scratchpads. To read 99 98 the values of all scratchpads, read the file. To write values, write a 100 99 series of pairs of scratchpad number and value 101 100 (eg: `echo '4 0x123 7 0xabc' > spad` 102 101 # to set scratchpads `4` and `7` to `0x123` and `0xabc`, respectively). 103 - * *hw*/peer\_spad - This file is used to read and write peer scratchpads. See 102 + * *hw*/peer\_spad 103 + This file is used to read and write peer scratchpads. See 104 104 *spad* for details. 105 105 106 - ## NTB Hardware Drivers 106 + NTB Hardware Drivers 107 + ==================== 107 108 108 109 NTB hardware drivers should register devices with the NTB core driver. After 109 110 registering, clients probe and remove functions will be called. 110 111 111 - ### NTB Intel Hardware Driver (ntb\_hw\_intel) 112 + NTB Intel Hardware Driver (ntb\_hw\_intel) 113 + ------------------------------------------ 112 114 113 115 The Intel hardware driver supports NTB on Xeon and Atom CPUs. 114 116 115 117 Module Parameters: 116 118 117 - * b2b\_mw\_idx - If the peer ntb is to be accessed via a memory window, then use 119 + * b2b\_mw\_idx 120 + If the peer ntb is to be accessed via a memory window, then use 118 121 this memory window to access the peer ntb. A value of zero or positive 119 122 starts from the first mw idx, and a negative value starts from the last 120 123 mw idx. Both sides MUST set the same value here! The default value is 121 124 `-1`. 122 - * b2b\_mw\_share - If the peer ntb is to be accessed via a memory window, and if 125 + * b2b\_mw\_share 126 + If the peer ntb is to be accessed via a memory window, and if 123 127 the memory window is large enough, still allow the client to use the 124 128 second half of the memory window for address translation to the peer. 125 - * xeon\_b2b\_usd\_bar2\_addr64 - If using B2B topology on Xeon hardware, use 129 + * xeon\_b2b\_usd\_bar2\_addr64 130 + If using B2B topology on Xeon hardware, use 126 131 this 64 bit address on the bus between the NTB devices for the window 127 132 at BAR2, on the upstream side of the link. 128 133 * xeon\_b2b\_usd\_bar4\_addr64 - See *xeon\_b2b\_bar2\_addr64*.