Skip to content

Commit 807ed6c

Browse files
jonathanpallantjonathanpallant
committed
Clean up nto-qnx target page
- Now explains what SDP is - Moves sections into a more useful order - Re-wrap long blocks of text
1 parent f43142b commit 807ed6c

1 file changed

Lines changed: 83 additions & 55 deletions

File tree

‎src/doc/rustc/src/platform-support/nto-qnx.md‎

Lines changed: 83 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,22 @@
1-
# Q
1+
# QNX
22

33
**Tier: 3**
44

5-
Support for the [QNX®][qnx.com] Software Development Platform (SDP), version 7.0, 7.1 and 8.0.
5+
Support for the [QNX®][qnx.com] [QNX Software Development Platform (SDP)], version 7.0, 7.1 and 8.0.
6+
7+
[QNX Software Development Platform (SDP)]: https://qnx.software/en/software/products-and-solutions/qnx-software-development-platform
8+
9+
The [QNX Software Development Platform (SDP)] is a development environment that
10+
you download and install on a host computer. It includes a C toolchain for your
11+
host, an IDE, and various board support packages for different target platforms.
12+
You can then use QNX SDP to build a custom run-time environment which you deploy
13+
onto an embedded device. That run-time environment will include a microkernel,
14+
whatever services you have selected, and perhaps one or more applications
15+
written in Rust.
16+
17+
In QNX SDP 7.x the run-time environment is based on QNX Neutrino RTOS 7.x, while
18+
in QNX SDP 8.0 the run-time environment is based on QNX OS 8.0. The name change
19+
reflects architectural changes in the RTOS, but both use a microkernel design.
620

721
## Target maintainers
822

@@ -24,44 +38,31 @@ The following QNX SDP versions and compilation targets are supported:
2438
| `aarch64-unknown-nto-qnx710` | QNX SDP 7.1 with io-pkt | AArch64 | ✓ | ✓ |
2539
| `x86_64-pc-nto-qnx710` | QNX SDP 7.1 with io-pkt | x86_64 | ✓ | ✓ |
2640
| `aarch64-unknown-nto-qnx700` | QNX SDP 7.0 | AArch64 | ? | ✓ |
27-
| `i686-pc-nto-qnx700` | QNX SDP 7.0 | x86 | | ✓ |
28-
29-
* On QNX SDP 7.0 and 7.1, `io-pkt` is used as network stack by default.
30-
* QNX SDP 7.1 includes the optional network stack `io-sock`.
31-
* QNX SDP 8.0 always uses `io-sock`.
32-
33-
Adding other architectures that are supported by QNX is possible.
34-
35-
In the table above, 'full support' indicates support for building Rust applications with the full standard library. A '?' means that support is in-progress. `no_std` support' is for building `#![no_std]` applications where only `core` and `alloc` are available.
36-
37-
For building or using the Rust toolchain for QNX, the relevant version of the [QNX Software Development Platform (SDP)] must be installed and initialized.
38-
Initialization is usually done by sourcing `qnxsdp-env.sh` (this will be installed as part of the SDP, see also installation instruction provided with the SDP).
39-
Afterwards [`qcc`](https://www.qnx.com/developers/docs/8.0/com.qnx.doc.neutrino.utilities/topic/q/qcc.html) (the QNX C/C++ compiler)
40-
should be available (in the `$PATH` variable).
41-
`qcc` will be called e.g. for linking executables.
42-
43-
[QNX Software Development Platform (SDP)]: https://qnx.software/en/software/products-and-solutions/qnx-software-development-platform
44-
45-
When linking `no_std` applications, they must link against `libc.so` (see example). This is
46-
required because applications always link against the `crt` library and `crt` depends on `libc.so`.
47-
This is done automatically when using the standard library.
41+
| `i686-pc-nto-qnx700` | QNX SDP 7.0 | x86 | - | ✓ |
4842

49-
### Disabling RELocation Read-Only (RELRO)
43+
* QNX SDP 7.0 only offers the `io-pkt` network stack
44+
* QNX SDP 7.1 uses the `io-pkt` network stack by default, but also includes the optional `io-sock` network stack
45+
* QNX SDP 8.0 only offers the `io-sock` network stack
5046

51-
While not recommended by default, some QNX kernel setups may require the `RELRO` to be disabled with `-C relro_level=off`, e.g. by adding it to the `.cargo/config.toml` file:
47+
In the table above, 'full support' indicates support for building Rust
48+
applications with the full standard library. A '?' means that support is
49+
in-progress. `no_std` support is for building `#![no_std]` applications where
50+
only `core` and `alloc` are available.
5251

53-
```toml
54-
[target.aarch64-unknown-nto-qnx700]
55-
rustflags = ["-C", "relro_level=off"]
56-
```
52+
For building or using the Rust toolchain for QNX, the relevant version of the
53+
[QNX Software Development Platform (SDP)] must be installed and initialized.
54+
Initialization is usually done by sourcing `qnxsdp-env.sh` (this will be
55+
installed as part of the SDP, so see the installation instruction provided with
56+
the SDP). Afterwards [`qcc`] (the QNX C/C++ compiler) should be available in
57+
your system PATH because it will be called during Rust compilation (e.g. for
58+
linking executables).
5759

58-
If your QNX kernel does not allow it, and `relro` is not disabled, running compiled binary would fail with `syntax error: ... unexpected` or similar. This is due to kernel trying to interpret compiled binary with `/bin/sh`, and obviously failing. To verify that this is really the case, run your binary with the `DL_DEBUG=all` env var, and look for this output. If you see it, you should disable `relro` as described above.
60+
[`qcc`]: https://www.qnx.com/developers/docs/8.0/com.qnx.doc.neutrino.utilities/topic/q/qcc.html
5961

60-
```text
61-
Resolution scope for Executable->/bin/sh:
62-
Executable->/bin/sh
63-
libc.so.4->/usr/lib/ldqnx-64.so.2
64-
```
62+
When linking `no_std` applications, they must link against `libc.so` (see
63+
example). This is required because applications always link against the `crt`
64+
library and `crt` depends on `libc.so`. This is done automatically when using
65+
the standard library.
6566

6667
## Conditional compilation
6768

@@ -127,18 +128,37 @@ For conditional compilation, the following QNX specific attributes are defined:
127128
rustc library/core library/alloc library/std
128129
```
129130

131+
## Building Rust programs
132+
133+
Rust does not ship pre-compiled artifacts for this target. To compile for this
134+
target, you must either build Rust with the target enabled (see "Building the
135+
target" above), or build your own copy of `core` by using `build-std` or
136+
similar.
137+
138+
Compiled executables can run directly on QNX, either by including them in the
139+
disk image, or copying them over the network to a running system.
140+
141+
Compiling C code requires the same environment variables to be set as compiling
142+
the Rust toolchain (see above), to ensure `qcc` is used with proper arguments.
143+
To ensure compatibility, do not specify any further arguments that for example
144+
change calling conventions or memory layout.
145+
130146
## Running the Rust test suite
131147

132-
The test suites of the Rust compiler and standard library can be executed much like other Rust targets.
133-
The environment for testing should match the one used during compiler compilation (refer to `build_env` and `qcc`/`PATH` above) with the
134-
addition of the TEST_DEVICE_ADDR environment variable.
135-
The TEST_DEVICE_ADDR variable controls the remote runner and should point to the target, despite localhost being shown in the following example.
136-
Note that some tests are failing which is why they are currently excluded by the target maintainers which can be seen in the following example.
148+
The test suites of the Rust compiler and standard library can be executed much
149+
like other Rust targets. The environment for testing should match the one used
150+
during compiler compilation (refer to `build_env` and `qcc`/`PATH` above) with
151+
the addition of the `TEST_DEVICE_ADDR` environment variable. The
152+
`TEST_DEVICE_ADDR` variable controls the remote runner and should point to a
153+
target running the `remote-test-server` executable.
154+
155+
Note that some tests are failing which is why they are currently excluded by the
156+
target maintainers which can be seen in the following example.
137157

138158
To run all tests on a x86_64 QNX Neutrino 7.1 target:
139159

140160
```bash
141-
export TEST_DEVICE_ADDR="localhost:12345" # must address the test target, can be a SSH tunnel
161+
export TEST_DEVICE_ADDR="1.2.3.4:12345" # must address the test target, can be a SSH tunnel
142162
export build_env=<see above>
143163

144164
# Disable tests that only work on the host or don't make sense for this target.
@@ -161,16 +181,6 @@ env $build_env \
161181
--target x86_64-pc-nto-qnx710
162182
```
163183

164-
## Building Rust programs
165-
166-
Rust does not ship pre-compiled artifacts for this target.
167-
To compile for this target, you must either build Rust with the target enabled (see "Building the target" above),
168-
or build your own copy of `core` by using `build-std` or similar.
169-
170-
## Testing
171-
172-
Compiled executables can run directly on QNX.
173-
174184
### Rust std library test suite
175185

176186
The target needs sufficient resources to execute all tests. The commands below assume that a QEMU image
@@ -230,8 +240,26 @@ is used.
230240
64 bytes from 127.0.0.1: icmp_seq=0 ttl=255 time=1 ms
231241
```
232242

233-
## Cross-compilation toolchains and C code
243+
## Disabling RELocation Read-Only (RELRO)
234244

235-
Compiling C code requires the same environment variables to be set as compiling the Rust toolchain (see above),
236-
to ensure `qcc` is used with proper arguments.
237-
To ensure compatibility, do not specify any further arguments that for example change calling conventions or memory layout.
245+
While not recommended by default, some QNX kernel setups may require the `RELRO`
246+
to be disabled with `-C relro_level=off`, e.g. by adding it to the
247+
`.cargo/config.toml` file:
248+
249+
```toml
250+
[target.aarch64-unknown-nto-qnx700]
251+
rustflags = ["-C", "relro_level=off"]
252+
```
253+
254+
If your QNX kernel does not allow it, and `relro` is not disabled, running
255+
compiled binary would fail with `syntax error: ... unexpected` or similar. This
256+
is due to kernel trying to interpret compiled binary with `/bin/sh`, and
257+
obviously failing. To verify that this is really the case, run your binary with
258+
the `DL_DEBUG=all` env var, and look for this output. If you see it, you should
259+
disable `relro` as described above.
260+
261+
```text
262+
Resolution scope for Executable->/bin/sh:
263+
Executable->/bin/sh
264+
libc.so.4->/usr/lib/ldqnx-64.so.2
265+
```

0 commit comments

Comments
 (0)