From 599448d8ca9d8d219a2b47d109ee86afb7468490 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 15 Jun 2020 08:50:20 +0200 Subject: docs: powerpc: convert vcpudispatch_stats.txt to ReST - Add a SPDX header; - Use standard markup for document title; - Adjust identation on lists and add blank lines where needed; - Add it to the powerpc index.rst file. Acked-by: Michael Ellerman # powerpc Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/a88855cc8b3a97b9b918a33e78e9ad000cf64be1.1592203650.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet --- Documentation/powerpc/index.rst | 1 + Documentation/powerpc/vcpudispatch_stats.rst | 75 ++++++++++++++++++++++++++++ Documentation/powerpc/vcpudispatch_stats.txt | 68 ------------------------- 3 files changed, 76 insertions(+), 68 deletions(-) create mode 100644 Documentation/powerpc/vcpudispatch_stats.rst delete mode 100644 Documentation/powerpc/vcpudispatch_stats.txt (limited to 'Documentation/powerpc') diff --git a/Documentation/powerpc/index.rst b/Documentation/powerpc/index.rst index afe2d5e54db6..748bf483b1c2 100644 --- a/Documentation/powerpc/index.rst +++ b/Documentation/powerpc/index.rst @@ -31,6 +31,7 @@ powerpc transactional_memory ultravisor vas-api + vcpudispatch_stats .. only:: subproject and html diff --git a/Documentation/powerpc/vcpudispatch_stats.rst b/Documentation/powerpc/vcpudispatch_stats.rst new file mode 100644 index 000000000000..5704657a5987 --- /dev/null +++ b/Documentation/powerpc/vcpudispatch_stats.rst @@ -0,0 +1,75 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======================== +VCPU Dispatch Statistics +======================== + +For Shared Processor LPARs, the POWER Hypervisor maintains a relatively +static mapping of the LPAR processors (vcpus) to physical processor +chips (representing the "home" node) and tries to always dispatch vcpus +on their associated physical processor chip. However, under certain +scenarios, vcpus may be dispatched on a different processor chip (away +from its home node). + +/proc/powerpc/vcpudispatch_stats can be used to obtain statistics +related to the vcpu dispatch behavior. Writing '1' to this file enables +collecting the statistics, while writing '0' disables the statistics. +By default, the DTLB log for each vcpu is processed 50 times a second so +as not to miss any entries. This processing frequency can be changed +through /proc/powerpc/vcpudispatch_stats_freq. + +The statistics themselves are available by reading the procfs file +/proc/powerpc/vcpudispatch_stats. Each line in the output corresponds to +a vcpu as represented by the first field, followed by 8 numbers. + +The first number corresponds to: + +1. total vcpu dispatches since the beginning of statistics collection + +The next 4 numbers represent vcpu dispatch dispersions: + +2. number of times this vcpu was dispatched on the same processor as last + time +3. number of times this vcpu was dispatched on a different processor core + as last time, but within the same chip +4. number of times this vcpu was dispatched on a different chip +5. number of times this vcpu was dispatches on a different socket/drawer + (next numa boundary) + +The final 3 numbers represent statistics in relation to the home node of +the vcpu: + +6. number of times this vcpu was dispatched in its home node (chip) +7. number of times this vcpu was dispatched in a different node +8. number of times this vcpu was dispatched in a node further away (numa + distance) + +An example output:: + + $ sudo cat /proc/powerpc/vcpudispatch_stats + cpu0 6839 4126 2683 30 0 6821 18 0 + cpu1 2515 1274 1229 12 0 2509 6 0 + cpu2 2317 1198 1109 10 0 2312 5 0 + cpu3 2259 1165 1088 6 0 2256 3 0 + cpu4 2205 1143 1056 6 0 2202 3 0 + cpu5 2165 1121 1038 6 0 2162 3 0 + cpu6 2183 1127 1050 6 0 2180 3 0 + cpu7 2193 1133 1052 8 0 2187 6 0 + cpu8 2165 1115 1032 18 0 2156 9 0 + cpu9 2301 1252 1033 16 0 2293 8 0 + cpu10 2197 1138 1041 18 0 2187 10 0 + cpu11 2273 1185 1062 26 0 2260 13 0 + cpu12 2186 1125 1043 18 0 2177 9 0 + cpu13 2161 1115 1030 16 0 2153 8 0 + cpu14 2206 1153 1033 20 0 2196 10 0 + cpu15 2163 1115 1032 16 0 2155 8 0 + +In the output above, for vcpu0, there have been 6839 dispatches since +statistics were enabled. 4126 of those dispatches were on the same +physical cpu as the last time. 2683 were on a different core, but within +the same chip, while 30 dispatches were on a different chip compared to +its last dispatch. + +Also, out of the total of 6839 dispatches, we see that there have been +6821 dispatches on the vcpu's home node, while 18 dispatches were +outside its home node, on a neighbouring chip. diff --git a/Documentation/powerpc/vcpudispatch_stats.txt b/Documentation/powerpc/vcpudispatch_stats.txt deleted file mode 100644 index e21476bfd78c..000000000000 --- a/Documentation/powerpc/vcpudispatch_stats.txt +++ /dev/null @@ -1,68 +0,0 @@ -VCPU Dispatch Statistics: -========================= - -For Shared Processor LPARs, the POWER Hypervisor maintains a relatively -static mapping of the LPAR processors (vcpus) to physical processor -chips (representing the "home" node) and tries to always dispatch vcpus -on their associated physical processor chip. However, under certain -scenarios, vcpus may be dispatched on a different processor chip (away -from its home node). - -/proc/powerpc/vcpudispatch_stats can be used to obtain statistics -related to the vcpu dispatch behavior. Writing '1' to this file enables -collecting the statistics, while writing '0' disables the statistics. -By default, the DTLB log for each vcpu is processed 50 times a second so -as not to miss any entries. This processing frequency can be changed -through /proc/powerpc/vcpudispatch_stats_freq. - -The statistics themselves are available by reading the procfs file -/proc/powerpc/vcpudispatch_stats. Each line in the output corresponds to -a vcpu as represented by the first field, followed by 8 numbers. - -The first number corresponds to: -1. total vcpu dispatches since the beginning of statistics collection - -The next 4 numbers represent vcpu dispatch dispersions: -2. number of times this vcpu was dispatched on the same processor as last - time -3. number of times this vcpu was dispatched on a different processor core - as last time, but within the same chip -4. number of times this vcpu was dispatched on a different chip -5. number of times this vcpu was dispatches on a different socket/drawer -(next numa boundary) - -The final 3 numbers represent statistics in relation to the home node of -the vcpu: -6. number of times this vcpu was dispatched in its home node (chip) -7. number of times this vcpu was dispatched in a different node -8. number of times this vcpu was dispatched in a node further away (numa -distance) - -An example output: - $ sudo cat /proc/powerpc/vcpudispatch_stats - cpu0 6839 4126 2683 30 0 6821 18 0 - cpu1 2515 1274 1229 12 0 2509 6 0 - cpu2 2317 1198 1109 10 0 2312 5 0 - cpu3 2259 1165 1088 6 0 2256 3 0 - cpu4 2205 1143 1056 6 0 2202 3 0 - cpu5 2165 1121 1038 6 0 2162 3 0 - cpu6 2183 1127 1050 6 0 2180 3 0 - cpu7 2193 1133 1052 8 0 2187 6 0 - cpu8 2165 1115 1032 18 0 2156 9 0 - cpu9 2301 1252 1033 16 0 2293 8 0 - cpu10 2197 1138 1041 18 0 2187 10 0 - cpu11 2273 1185 1062 26 0 2260 13 0 - cpu12 2186 1125 1043 18 0 2177 9 0 - cpu13 2161 1115 1030 16 0 2153 8 0 - cpu14 2206 1153 1033 20 0 2196 10 0 - cpu15 2163 1115 1032 16 0 2155 8 0 - -In the output above, for vcpu0, there have been 6839 dispatches since -statistics were enabled. 4126 of those dispatches were on the same -physical cpu as the last time. 2683 were on a different core, but within -the same chip, while 30 dispatches were on a different chip compared to -its last dispatch. - -Also, out of the total of 6839 dispatches, we see that there have been -6821 dispatches on the vcpu's home node, while 18 dispatches were -outside its home node, on a neighbouring chip. -- cgit v1.2.3 From cadcb83f8db9de0ee123917f0e9f96b96bf069a2 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 23 Jun 2020 09:09:07 +0200 Subject: docs: powerpc: fix some issues at vas-api.rst There are a few issues on this document, when built via the building with ``make htmldocs``: Documentation/powerpc/vas-api.rst:116: WARNING: Unexpected indentation. Documentation/powerpc/vas-api.rst:116: WARNING: Inline emphasis start-string without end-string. Documentation/powerpc/vas-api.rst:117: WARNING: Block quote ends without a blank line; unexpected unindent. Documentation/powerpc/vas-api.rst:117: WARNING: Inline emphasis start-string without end-string. Documentation/powerpc/vas-api.rst:120: WARNING: Definition list ends without a blank line; unexpected unindent. Documentation/powerpc/vas-api.rst:124: WARNING: Unexpected indentation. Documentation/powerpc/vas-api.rst:133: WARNING: Unexpected indentation. Documentation/powerpc/vas-api.rst:135: WARNING: Unexpected indentation. Documentation/powerpc/vas-api.rst:150: WARNING: Unexpected indentation. Documentation/powerpc/vas-api.rst:151: WARNING: Block quote ends without a blank line; unexpected unindent. Documentation/powerpc/vas-api.rst:161: WARNING: Unexpected indentation. Documentation/powerpc/vas-api.rst:176: WARNING: Definition list ends without a blank line; unexpected unindent. Documentation/powerpc/vas-api.rst:253: WARNING: Unexpected indentation. Documentation/powerpc/vas-api.rst:253: WARNING: Inline emphasis start-string without end-string. Documentation/powerpc/vas-api.rst:259: WARNING: Unexpected indentation. Documentation/powerpc/vas-api.rst:261: WARNING: Block quote ends without a blank line; unexpected unindent. Documentation/powerpc/vas-api.rst:266: WARNING: Unexpected indentation. Documentation/powerpc/vas-api.rst:267: WARNING: Block quote ends without a blank line; unexpected unindent. Documentation/powerpc/vas-api.rst:270: WARNING: Definition list ends without a blank line; unexpected unindent. Documentation/powerpc/vas-api.rst:271: WARNING: Definition list ends without a blank line; unexpected unindent. Documentation/powerpc/vas-api.rst:273: WARNING: Unexpected indentation. Documentation/powerpc/vas-api.rst:274: WARNING: Block quote ends without a blank line; unexpected unindent. Documentation/powerpc/vas-api.rst:277: WARNING: Definition list ends without a blank line; unexpected unindent. Documentation/powerpc/vas-api.rst:278: WARNING: Definition list ends without a blank line; unexpected unindent. Documentation/powerpc/vas-api.rst:280: WARNING: Unexpected indentation. Documentation/powerpc/vas-api.rst:287: WARNING: Block quote ends without a blank line; unexpected unindent. Documentation/powerpc/vas-api.rst:289: WARNING: Block quote ends without a blank line; unexpected unindent. Fixes: c12e38b1d52e ("Documentation/powerpc: VAS API") Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/fc1138e563bc3a41a9e59b5dd1fe2f6a4bfad253.1592895969.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet --- Documentation/powerpc/vas-api.rst | 23 ++++++++++++++++++----- 1 file changed, 18 insertions(+), 5 deletions(-) (limited to 'Documentation/powerpc') diff --git a/Documentation/powerpc/vas-api.rst b/Documentation/powerpc/vas-api.rst index 1217c2f1595e..b7fdbe560010 100644 --- a/Documentation/powerpc/vas-api.rst +++ b/Documentation/powerpc/vas-api.rst @@ -87,6 +87,7 @@ Applications may chose a specific instance of the NX co-processor using the vas_id field in the VAS_TX_WIN_OPEN ioctl as detailed below. A userspace library libnxz is available here but still in development: + https://github.com/abalib/power-gzip Applications that use inflate / deflate calls can link with libnxz @@ -110,6 +111,7 @@ Applications should use the VAS_TX_WIN_OPEN ioctl as follows to establish a connection with NX co-processor engine: :: + struct vas_tx_win_open_attr { __u32 version; __s16 vas_id; /* specific instance of vas or -1 @@ -119,8 +121,10 @@ a connection with NX co-processor engine: __u64 reserved2[6]; }; - version: The version field must be currently set to 1. - vas_id: If '-1' is passed, kernel will make a best-effort attempt + version: + The version field must be currently set to 1. + vas_id: + If '-1' is passed, kernel will make a best-effort attempt to assign an optimal instance of NX for the process. To select the specific VAS instance, refer "Discovery of available VAS engines" section below. @@ -129,7 +133,8 @@ a connection with NX co-processor engine: and must be set to 0. The attributes attr for the VAS_TX_WIN_OPEN ioctl are defined as - follows: + follows:: + #define VAS_MAGIC 'v' #define VAS_TX_WIN_OPEN _IOW(VAS_MAGIC, 1, struct vas_tx_win_open_attr) @@ -141,6 +146,8 @@ a connection with NX co-processor engine: returns -1 and sets the errno variable to indicate the error. Error conditions: + + ====== ================================================ EINVAL fd does not refer to a valid VAS device. EINVAL Invalid vas ID EINVAL version is not set with proper value @@ -149,6 +156,7 @@ a connection with NX co-processor engine: ENOSPC System has too many active windows (connections) opened EINVAL reserved fields are not set to 0. + ====== ================================================ See the ioctl(2) man page for more details, error codes and restrictions. @@ -158,11 +166,13 @@ mmap() NX-GZIP device The mmap() system call for a NX-GZIP device fd returns a paste_address that the application can use to copy/paste its CRB to the hardware engines. + :: paste_addr = mmap(addr, size, prot, flags, fd, offset); Only restrictions on mmap for a NX-GZIP device fd are: + * size should be PAGE_SIZE * offset parameter should be 0ULL @@ -170,10 +180,12 @@ that the application can use to copy/paste its CRB to the hardware engines. In addition to the error conditions listed on the mmap(2) man page, can also fail with one of the following error codes: + ====== ============================================= EINVAL fd is not associated with an open window (i.e mmap() does not follow a successful call to the VAS_TX_WIN_OPEN ioctl). EINVAL offset field is not 0ULL. + ====== ============================================= Discovery of available VAS engines ================================== @@ -210,7 +222,7 @@ In case if NX encounters translation error (called NX page fault) on CSB address or any request buffer, raises an interrupt on the CPU to handle the fault. Page fault can happen if an application passes invalid addresses or request buffers are not in memory. The operating system handles the fault by -updating CSB with the following data: +updating CSB with the following data:: csb.flags = CSB_V; csb.cc = CSB_CC_TRANSLATION; @@ -223,7 +235,7 @@ the application can resend this request to NX. If the OS can not update CSB due to invalid CSB address, sends SEGV signal to the process who opened the send window on which the original request was -issued. This signal returns with the following siginfo struct: +issued. This signal returns with the following siginfo struct:: siginfo.si_signo = SIGSEGV; siginfo.si_errno = EFAULT; @@ -248,6 +260,7 @@ Simple example ============== :: + int use_nx_gzip() { int rc, fd; -- cgit v1.2.3 From e77bfed07229011f1403d391091c9afc6f2e4d74 Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Tue, 7 Jul 2020 11:04:09 -0700 Subject: Documentation: powerpc/vas-api: eliminate duplicated word Drop the doubled word "the". Signed-off-by: Randy Dunlap Cc: Jonathan Corbet Cc: linux-doc@vger.kernel.org Cc: Michael Ellerman Cc: Benjamin Herrenschmidt Cc: Paul Mackerras Cc: linuxppc-dev@lists.ozlabs.org Link: https://lore.kernel.org/r/20200707180414.10467-16-rdunlap@infradead.org Signed-off-by: Jonathan Corbet --- Documentation/powerpc/vas-api.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/powerpc') diff --git a/Documentation/powerpc/vas-api.rst b/Documentation/powerpc/vas-api.rst index b7fdbe560010..d6dbfcbae916 100644 --- a/Documentation/powerpc/vas-api.rst +++ b/Documentation/powerpc/vas-api.rst @@ -43,7 +43,7 @@ engine for this process. Once a connection is established, the application should use the mmap() system call to map the hardware address of engine's request queue into the application's virtual address space. -The application can then submit one or more requests to the the engine by +The application can then submit one or more requests to the engine by using copy/paste instructions and pasting the CRBs to the virtual address (aka paste_address) returned by mmap(). User space can close the established connection or send window by closing the file descriptior -- cgit v1.2.3