From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> To: Linux Doc Mailing List <linux-doc@vger.kernel.org> Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>, linux-kernel@vger.kernel.org, Jonathan Corbet <corbet@lwn.net>, Michael Ellerman <mpe@ellerman.id.au>, Benjamin Herrenschmidt <benh@kernel.crashing.org>, Paul Mackerras <paulus@samba.org>, Sukadev Bhattiprolu <sukadev@linux.ibm.com>, Haren Myneni <haren@linux.ibm.com>, linuxppc-dev@lists.ozlabs.org Subject: [PATCH v2 11/15] docs: powerpc: fix some issues at vas-api.rst Date: Tue, 23 Jun 2020 09:09:07 +0200 [thread overview] Message-ID: <fc1138e563bc3a41a9e59b5dd1fe2f6a4bfad253.1592895969.git.mchehab+huawei@kernel.org> (raw) In-Reply-To: <cover.1592895969.git.mchehab+huawei@kernel.org> 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 <mchehab+huawei@kernel.org> --- Documentation/powerpc/vas-api.rst | 23 ++++++++++++++++++----- 1 file changed, 18 insertions(+), 5 deletions(-) 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; -- 2.26.2
WARNING: multiple messages have this Message-ID (diff)
From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> To: Linux Doc Mailing List <linux-doc@vger.kernel.org> Cc: Jonathan Corbet <corbet@lwn.net>, Mauro Carvalho Chehab <mchehab+huawei@kernel.org>, Haren Myneni <haren@linux.ibm.com>, linux-kernel@vger.kernel.org, Paul Mackerras <paulus@samba.org>, Sukadev Bhattiprolu <sukadev@linux.ibm.com>, linuxppc-dev@lists.ozlabs.org Subject: [PATCH v2 11/15] docs: powerpc: fix some issues at vas-api.rst Date: Tue, 23 Jun 2020 09:09:07 +0200 [thread overview] Message-ID: <fc1138e563bc3a41a9e59b5dd1fe2f6a4bfad253.1592895969.git.mchehab+huawei@kernel.org> (raw) In-Reply-To: <cover.1592895969.git.mchehab+huawei@kernel.org> 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 <mchehab+huawei@kernel.org> --- Documentation/powerpc/vas-api.rst | 23 ++++++++++++++++++----- 1 file changed, 18 insertions(+), 5 deletions(-) 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; -- 2.26.2
next prev parent reply other threads:[~2020-06-23 7:09 UTC|newest] Thread overview: 29+ messages / expand[flat|nested] mbox.gz Atom feed top 2020-06-23 7:08 [PATCH v2 00/15] Documentation fixes Mauro Carvalho Chehab 2020-06-23 7:08 ` Mauro Carvalho Chehab 2020-06-23 7:08 ` Mauro Carvalho Chehab 2020-06-23 7:08 ` [PATCH v2 01/15] mm: vmalloc.c: remove a kernel-doc annotation from a removed parameter Mauro Carvalho Chehab 2020-06-23 7:08 ` [PATCH v2 02/15] net: dev: add a missing kernel-doc annotation Mauro Carvalho Chehab 2020-06-23 7:08 ` [PATCH v2 03/15] net: netdevice.h: add a description for napi_defer_hard_irqs Mauro Carvalho Chehab 2020-06-23 7:09 ` [PATCH v2 04/15] scripts/kernel-doc: parse __ETHTOOL_DECLARE_LINK_MODE_MASK Mauro Carvalho Chehab 2020-06-23 7:09 ` [PATCH v2 05/15] net: pylink.h: add kernel-doc descriptions for new fields at phylink_config Mauro Carvalho Chehab 2020-06-23 9:07 ` Russell King - ARM Linux admin 2020-06-23 7:09 ` [PATCH v2 06/15] scripts/kernel-doc: handle function pointer prototypes Mauro Carvalho Chehab 2020-06-23 7:09 ` [PATCH v2 07/15] fs: fs.h: fix a kernel-doc parameter description Mauro Carvalho Chehab 2020-06-23 7:09 ` [PATCH v2 08/15] kcsan: fix a kernel-doc warning Mauro Carvalho Chehab 2020-06-23 7:09 ` [PATCH v2 09/15] selftests/vm/keys: fix a broken reference at protection_keys.c Mauro Carvalho Chehab 2020-06-23 7:09 ` [PATCH v2 10/15] docs: hugetlbpage.rst: fix some warnings Mauro Carvalho Chehab 2020-06-23 17:38 ` Mike Kravetz 2020-06-23 7:09 ` Mauro Carvalho Chehab [this message] 2020-06-23 7:09 ` [PATCH v2 11/15] docs: powerpc: fix some issues at vas-api.rst Mauro Carvalho Chehab 2020-06-23 7:09 ` [PATCH v2 12/15] docs: driver-model: remove a duplicated markup at driver.rst Mauro Carvalho Chehab 2020-06-23 7:09 ` [PATCH v2 13/15] docs: ABI: fix a typo when pointing to w1-generic.rst Mauro Carvalho Chehab 2020-06-23 7:09 ` [PATCH v2 14/15] docs: fix references for DMA*.txt files Mauro Carvalho Chehab 2020-06-23 7:09 ` Mauro Carvalho Chehab 2020-06-23 7:09 ` Mauro Carvalho Chehab 2020-06-23 7:22 ` Christoph Hellwig 2020-06-23 7:22 ` Christoph Hellwig 2020-06-23 7:22 ` Christoph Hellwig 2020-06-23 7:09 ` [PATCH v2 15/15] docs: fs: proc.rst: convert a new chapter to ReST Mauro Carvalho Chehab 2020-06-26 16:13 ` [PATCH v2 00/15] Documentation fixes Jonathan Corbet 2020-06-26 16:13 ` Jonathan Corbet 2020-06-26 16:13 ` Jonathan Corbet
Reply instructions: You may reply publicly to this message via plain-text email using any one of the following methods: * Save the following mbox file, import it into your mail client, and reply-to-all from there: mbox Avoid top-posting and favor interleaved quoting: https://en.wikipedia.org/wiki/Posting_style#Interleaved_style * Reply using the --to, --cc, and --in-reply-to switches of git-send-email(1): git send-email \ --in-reply-to=fc1138e563bc3a41a9e59b5dd1fe2f6a4bfad253.1592895969.git.mchehab+huawei@kernel.org \ --to=mchehab+huawei@kernel.org \ --cc=benh@kernel.crashing.org \ --cc=corbet@lwn.net \ --cc=haren@linux.ibm.com \ --cc=linux-doc@vger.kernel.org \ --cc=linux-kernel@vger.kernel.org \ --cc=linuxppc-dev@lists.ozlabs.org \ --cc=mpe@ellerman.id.au \ --cc=paulus@samba.org \ --cc=sukadev@linux.ibm.com \ /path/to/YOUR_REPLY https://kernel.org/pub/software/scm/git/docs/git-send-email.html * If your mail client supports setting the In-Reply-To header via mailto: links, try the mailto: linkBe sure your reply has a Subject: header at the top and a blank line before the message body.
This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.