Commit cadcb83f authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab Committed by Jonathan Corbet

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: c12e38b1 ("Documentation/powerpc: VAS API")
Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/fc1138e563bc3a41a9e59b5dd1fe2f6a4bfad253.1592895969.git.mchehab+huawei@kernel.orgSigned-off-by: default avatarJonathan Corbet <corbet@lwn.net>
parent 72a3e3e2
...@@ -87,6 +87,7 @@ Applications may chose a specific instance of the NX co-processor using ...@@ -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. 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: A userspace library libnxz is available here but still in development:
https://github.com/abalib/power-gzip https://github.com/abalib/power-gzip
Applications that use inflate / deflate calls can link with libnxz 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 ...@@ -110,6 +111,7 @@ Applications should use the VAS_TX_WIN_OPEN ioctl as follows to establish
a connection with NX co-processor engine: a connection with NX co-processor engine:
:: ::
struct vas_tx_win_open_attr { struct vas_tx_win_open_attr {
__u32 version; __u32 version;
__s16 vas_id; /* specific instance of vas or -1 __s16 vas_id; /* specific instance of vas or -1
...@@ -119,8 +121,10 @@ a connection with NX co-processor engine: ...@@ -119,8 +121,10 @@ a connection with NX co-processor engine:
__u64 reserved2[6]; __u64 reserved2[6];
}; };
version: The version field must be currently set to 1. version:
vas_id: If '-1' is passed, kernel will make a best-effort attempt 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 to assign an optimal instance of NX for the process. To
select the specific VAS instance, refer select the specific VAS instance, refer
"Discovery of available VAS engines" section below. "Discovery of available VAS engines" section below.
...@@ -129,7 +133,8 @@ a connection with NX co-processor engine: ...@@ -129,7 +133,8 @@ a connection with NX co-processor engine:
and must be set to 0. and must be set to 0.
The attributes attr for the VAS_TX_WIN_OPEN ioctl are defined as The attributes attr for the VAS_TX_WIN_OPEN ioctl are defined as
follows: follows::
#define VAS_MAGIC 'v' #define VAS_MAGIC 'v'
#define VAS_TX_WIN_OPEN _IOW(VAS_MAGIC, 1, #define VAS_TX_WIN_OPEN _IOW(VAS_MAGIC, 1,
struct vas_tx_win_open_attr) struct vas_tx_win_open_attr)
...@@ -141,6 +146,8 @@ a connection with NX co-processor engine: ...@@ -141,6 +146,8 @@ a connection with NX co-processor engine:
returns -1 and sets the errno variable to indicate the error. returns -1 and sets the errno variable to indicate the error.
Error conditions: Error conditions:
====== ================================================
EINVAL fd does not refer to a valid VAS device. EINVAL fd does not refer to a valid VAS device.
EINVAL Invalid vas ID EINVAL Invalid vas ID
EINVAL version is not set with proper value EINVAL version is not set with proper value
...@@ -149,6 +156,7 @@ a connection with NX co-processor engine: ...@@ -149,6 +156,7 @@ a connection with NX co-processor engine:
ENOSPC System has too many active windows (connections) ENOSPC System has too many active windows (connections)
opened opened
EINVAL reserved fields are not set to 0. EINVAL reserved fields are not set to 0.
====== ================================================
See the ioctl(2) man page for more details, error codes and See the ioctl(2) man page for more details, error codes and
restrictions. restrictions.
...@@ -158,11 +166,13 @@ mmap() NX-GZIP device ...@@ -158,11 +166,13 @@ mmap() NX-GZIP device
The mmap() system call for a NX-GZIP device fd returns a paste_address 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. that the application can use to copy/paste its CRB to the hardware engines.
:: ::
paste_addr = mmap(addr, size, prot, flags, fd, offset); paste_addr = mmap(addr, size, prot, flags, fd, offset);
Only restrictions on mmap for a NX-GZIP device fd are: Only restrictions on mmap for a NX-GZIP device fd are:
* size should be PAGE_SIZE * size should be PAGE_SIZE
* offset parameter should be 0ULL * offset parameter should be 0ULL
...@@ -170,10 +180,12 @@ that the application can use to copy/paste its CRB to the hardware engines. ...@@ -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 In addition to the error conditions listed on the mmap(2) man
page, can also fail with one of the following error codes: page, can also fail with one of the following error codes:
====== =============================================
EINVAL fd is not associated with an open window EINVAL fd is not associated with an open window
(i.e mmap() does not follow a successful call (i.e mmap() does not follow a successful call
to the VAS_TX_WIN_OPEN ioctl). to the VAS_TX_WIN_OPEN ioctl).
EINVAL offset field is not 0ULL. EINVAL offset field is not 0ULL.
====== =============================================
Discovery of available VAS engines Discovery of available VAS engines
================================== ==================================
...@@ -210,7 +222,7 @@ In case if NX encounters translation error (called NX page fault) on CSB ...@@ -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 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 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 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.flags = CSB_V;
csb.cc = CSB_CC_TRANSLATION; csb.cc = CSB_CC_TRANSLATION;
...@@ -223,7 +235,7 @@ the application can resend this request to NX. ...@@ -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 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 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_signo = SIGSEGV;
siginfo.si_errno = EFAULT; siginfo.si_errno = EFAULT;
...@@ -248,6 +260,7 @@ Simple example ...@@ -248,6 +260,7 @@ Simple example
============== ==============
:: ::
int use_nx_gzip() int use_nx_gzip()
{ {
int rc, fd; int rc, fd;
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment