Re: Control file
Bastien Roucariès wrote:
> Could you please improve the package description ?
I've nearly got a patch, but I'll need to pause my work on this for
now so I'll just include my work so far.
> Source: isa-support
> Section: misc
> Priority: optional
> Uploaders: Gioele Barabucci <gioele@svario.it>
> Maintainer: Bastien Roucariès <rouca@debian.org>
> Build-Depends: debhelper-compat (= 13), po-debconf
> Standards-Version: 4.6.1
> Rules-Requires-Root: no
> Vcs-Git: https://salsa.debian.org/debian/isa-support.git
> Vcs-Browser: https://salsa.debian.org/debian/isa-support
>
> Package: isa-support
Nothing ever explains what ISA stands for (or that Instruction Set
Architecture means "CPU features"). Remember, even within the field
of computer hardware initialisms it also has an alternative
interpretation as an old expansion card slot type... Thankyou for
reminding me how good it is not to have any devices with ISA slots.
(Staying on the topic of how out of date I am: is it still safe to use
"CPU" as a shorthand for "(micro)processor", or are people going to
object that some of them might be APUs?)
> Multi-Arch: same
> Architecture: any-i386 any-i386 any-amd64 armel armel armhf armhf powerpc
> Depends: ${shlibs:Depends}, ${misc:Depends}
> Description: test for architecture features
These synopses are all basically verb phrases where the DevRef
recommendation is (anarthrous) noun phrases, to explain what kind of
thing this package is. Unfortunately it's an unusual kind of thing
that we don't have an established label for... but in effect this one
is a "foo-common" package, right? So it might use a description like
Description: CPU feature checking - common back-end
Then I'd recommend giving each package in the family the same short
first paragraph explaining the general idea before the paragraphs
explaining how the particular package fits into that system. I'm told
this scheme of standard paragraphs makes life easier for translators.
> The isa-support package contains test programs that probe for architecture
> features like SSE3. Other packages can use these to prevent installation on
> machines that lack these features. For convenience, there are individual
> packages for each feature that other packages can pre-depend on:
"Test programs" makes it sound as if they're utilities in /sbin or
somewhere rather than /usr/libexec. Then I'm trying to turn it round
to put the focus on what packages like chromium need to do:
The packages in the isa-support family can be used to probe for
microprocessor Instruction Set Architecture features such as SSE3. By
refusing to install on a machine that lacks particular required features,
they allow instruction set requirements to be handled in terms of package
dependencies.
.
This package provides the feature-probing infrastructure. To assert a
CPU requirement, other packages can pre-depend on one of the individual
feature-specific packages:
> .
> sse2-support, sse3-support, sse4.2-support, altivec-support, neon-support,
> armv6-support, armv7-support, armv8-support, vfp-support, vfpv2-support,
> vfpv3-support
I'm going to resist the urge to alphabeticise these, on the assumption
that sorting them by architecture is more convenient for you.
>
> Package: sse2-support
> Multi-Arch: foreign
> Architecture: any-i386
> Pre-Depends: isa-support (= ${binary:Version})
> Description: prevent installation on processors without required sse2 instructions
I want to somehow convert this into a short noun phrase (and
capitalise the initialisms in passing), and preferably make it
fit neatly alongside isa-support as well... how about:
Description: CPU feature checking - require SSE2
Debian users might find it natural to talk about "asserting" a
requirement, so we could say
Description: CPU feature checking - assert SSE2 requirement
but there's also a danger that the people who find this natural would
also expect it to work literally as an "assert()", so I've avoided
that for now.
Then insert the shared intro paragraph:
The packages in the isa-support family can be used to probe for
microprocessor Instruction Set Architecture features such as SSE3. By
refusing to install on a machine that lacks particular required features,
they allow instruction set requirements to be handled in terms of package
dependencies.
Then on to "how this particular package fits in":
> This is a mostly dummy package, whose only purpose is to detect the presence
> of sse2. It refuses to install on inadequate processors, thus allowing
> specifying such a requirement as a dependency.
This can be shorter now:
This is a mostly dummy package which checks for SSE2 and refuses to
install on unsupported hardware.
Instead of "mostly dummy" it might make sense to call it a
*dependency* package, since people sometimes use "dummy package"
specifically to mean a transitional package (and since dependency
packages aren't always completely empty). For now I'm leaving it as
"dummy package".
> .
> Streaming SIMD Extensions (SSE) is a single instruction,
> multiple data (SIMD) instruction set extension.
No problem here, except that there's a missing paragraph between
this definition of SSE and the claim that these instructions came in
with Pentium 4. No, SSE was available in P3; it was SSE*2* that came
in with P4. So insert:
SSE2 was an incremental upgrade to SSE intended to fully replace the
earlier MMX instruction set.
(Unfortunately MMX is legally expansionless.)
> .
> These instructions are available on processors from Pentium 4 onward,
> including any 64-bit capable. There's no SSE2 on Pentium 3, Athlon XP,
> Via C3, Quark -- and older.
I'm cutting down slightly on discussion of particular "instructions"
in favour of "features" (meaning the complete sets of instructions
that these packages actually test for).
This feature is available on processors from Pentium 4 onward, including
all 64-bit capable ones. It is not available on Pentium 3, Athlon XP,
Via C3, Quark, or older processors.
> Package: sse3-support
> Multi-Arch: foreign
> Architecture: any-i386 any-amd64
> Pre-Depends: isa-support (= ${binary:Version})
> Description: prevent installation on processors without required sse3 instructions
> This is a mostly dummy package, whose only purpose is to detect the presence
> of sse3. It refuses to install on inadequate processors, thus allowing
> specifying such a requirement as a dependency.
Again:
Description: CPU feature checking - require SSE3
The packages in the isa-support family can be used to probe for
microprocessor Instruction Set Architecture features such as SSE3. By
refusing to install on a machine that lacks particular required features,
they allow instruction set requirements to be handled in terms of package
dependencies.
.
This is a mostly dummy package which checks for SSE3 and refuses to
install on unsupported hardware.
> .
> Streaming SIMD Extensions (SSE) is a single instruction,
> multiple data (SIMD) instruction set extension.
> .
> SSE3, also called Prescott New Instructions (PNI), is an incremental upgrade
> to SSE2, adding a handful of DSP-oriented mathematics.
"A handful of mathematics"? I think you need something that works as a
count noun, like "operations".
DSP expands to "digital signal processing" (or sometimes "processor",
though not in the CPU sense of the word); but expanding the acronym
doesn't really convey what it's talking about. After all, pretty much
anything a computer does is digital processing of what are in effect
signals; the particular task that "DSP" deals with is converting
audiovisual media formats. So maybe it should say something like
SSE3, also called PNI (Prescott New Instructions), is an incremental upgrade
to SSE2, adding a handful of new operations useful for processing media.
> .
> These instructions are available on almost any 64-bit capable processors
> except for some early AMD models (Sledgehammer and Clawhammer), but not
> most 32-bit only hardware.
This feature is available on almost any 64-bit-capable processor except for
some early AMD models (Sledgehammer and Clawhammer), but is not available on
most 32-bit-only hardware.
>
> Package: sse4.1-support
> Multi-Arch: foreign
> Architecture: any-i386 any-amd64
> Pre-Depends: isa-support (= ${binary:Version})
> Description: prevent installation on processors without required sse4.1 instructions
> This is a mostly dummy package, whose only purpose is to detect the presence
> of sse4.1. It refuses to install on inadequate processors, thus allowing
> specifying such a requirement as a dependency.
> .
> Streaming SIMD Extensions (SSE) is a single instruction,
> multiple data (SIMD) instruction set extension.
All as above...
> .
> This intruction set added a dot product instruction and additional
> integer instructions.
Recurring typo: inStruction. But that's three uses of the word in the
same sentence; I'd recommend starting by saying *which* instruction set
we're talking about:
SSE4.1 added a dot product instruction and additional integer
instructions.
> .
> These instructions are available on Intel processors since Penryn (circa
> 2008), but notably not on anything AMD until 2011-13, starting with family
> 15h (Bulldozer then Jaguar).
Wikipedia tells me Bulldozer came out in late 2011, so why "2011-13"?
Jaguar arrived later, but if AMD were selling SSE4.1-capable CPUs
before then, we can't say it was "not on anything AMD" at that point.
And apparently it went: Bobcat=14h; Jaguar=16h; Puma=16h (2nd-gen).
Maybe we could make it:
This feature is available on Intel processors since Penryn (circa 2008),
but notably not on anything AMD until the Bulldozer (15h, in 2011) and
Jaguar (16h, in 2013) families.
> Package: sse4.2-support
> Multi-Arch: foreign
> Architecture: any-i386 any-amd64
> Pre-Depends: isa-support (= ${binary:Version})
> Description: prevent installation on processors without required sse4.2 instructions
> This is a mostly dummy package, whose only purpose is to detect the presence
> of sse4.2. It refuses to install on inadequate processors, thus allowing
> specifying such a requirement as a dependency.
> .
> Streaming SIMD Extensions (SSE) is a single instruction,
> multiple data (SIMD) instruction set extension.
> .
> This intruction set added STTNI (String and Text New Instructions),
> several new instructions that perform character searches
> and comparison on two operands of 16 bytes at a time.
Wikipedia assures me this is all true and STTNI stands for String and
Text New Instructions (what, they couldn't be bothered to find a way
to make it come out as STTNG?) Tracking it back to the intel.com
source, I find this actually implies STTNI stands for "String and Text
processing" - so presumably ST plus the same TNI as the "Tejas New
Instructions" feature also known as *S*SSE3; but whether that's true
or not I'd rather keep these worms in their can... maybe:
SSE4.2 added string and text processing instructions that perform
character searches and comparison on two operands of 16 bytes at a time.
> .
> These instructions are available on Intel processors since Nehalem (circa
> 2008), but notably not on anything AMD until 2011-13, starting with family
> 15h (Bulldozer then Jaguar).
As above:
This feature is available on Intel processors since Nehalem (circa 2008),
but notably not on anything AMD until the Bulldozer (15h, in 2011) and
Jaguar (16h, in 2013) families.
> Package: altivec-support
> Multi-Arch: foreign
> Architecture: powerpc
> Pre-Depends: isa-support (= ${binary:Version})
> Description: prevent installation on processors without required altivec instructions
> This is a mostly dummy package, whose only purpose is to detect the presence
> of altivec. It refuses to install on inadequate processors, thus allowing
> specifying such a requirement as a dependency.
> .
> AltiVec is a single-precision floating point and integer SIMD instruction set
> AltiVec is a standard part of the Power ISA v.2.03 specification.
Make that capitalisation consistent, and sort out the odd repetitive
unpunctuated lines - from the top:
Description: CPU feature checking - require AltiVec
The packages in the isa-support family can be used to probe for
microprocessor Instruction Set Architecture features such as SSE3. By
refusing to install on a machine that lacks particular required features,
they allow instruction set requirements to be handled in terms of package
dependencies.
.
This is a mostly dummy package which checks for AltiVec and refuses to
install on unsupported hardware.
.
AltiVec is a single-precision floating point and integer SIMD instruction
set. It is a standard part of the Power ISA v.2.03 specification.
Hrmm, so ARM users are expected to know what SIMD stands for?
And there really is a dot after the V in "v.2.03", how peculiar.
> Package: neon-support
> Multi-Arch: foreign
> Architecture: armhf
> Pre-Depends: isa-support (= ${binary:Version})
> Description: prevent installation on processors without required neon instructions
> This is a mostly dummy package, whose only purpose is to detect the presence
> of neon. It refuses to install on inadequate processors, thus allowing
> specifying such a requirement as a dependency.
> .
As above. Next for some reason instead of explaining what "Neon" is
it explains a different thing and mentions Neon as one of its aliases:
> The Advanced SIMD extension (aka Neon or "MPE" Media Processing Engine)
> is a combined 64- and 128-bit SIMD instruction set that provides
> standardised acceleration for media and signal processing applications.
Neon, also known as MPE (Media Processing Engine) or Advanced SIMD, is a
combined 64- and 128-bit SIMD instruction set that provides standardised
acceleration for media and signal processing applications.
(I'm not going to standardiZe the localiZation if you're more used
to ISE support.)
> .
> These instructions are available on the vast majority of armhf hardware
> but not guaranteed before ARMv8 (ie, 64-bit capable).
Majorities need to be countable, which -ware words aren't. And this
is another adjective-final sentence where English would need to end in
a dummy noun like "ones", so reorganise slightly:
This feature is available on the vast majority of armhf devices but not
guaranteed before the 64-bit capable ARMv8.
> Package: armv6-support
> Multi-Arch: foreign
> Architecture: armel
> Pre-Depends: isa-support (= ${binary:Version})
> Description: prevent installation on processors without required armv6 instructions
> This is a mostly dummy package, whose only purpose is to detect the presence
> of armv6. It refuses to install on inadequate processors, thus allowing
> specifying such a requirement as a dependency.
> .
As above.
> This architecture is available the newer armel machine like
> for instance Raspberry Pi, but not guaranted by architecture
> baseline.
> .
> Cache is physically addressed, solving many cache aliasing problems
> and reducing context switch overhead.
> Unaligned and mixed-endian data access is supported.
> This architecture includes the first version of Thumb technology.
> .
> This architecture is available since ARM11 product
> family including ARM1136J(F)-S, ARM1156T2(F)-S,
> ARM1176JZ(F)-S, ARM1136EJ(F)-S and ARM11MPCore
> processors. Boards include the Raspberry Pi model 1 and
> Raspberry Pi Zero. This architecture should not be confused
> with product family ARM6.
This needs a bit more work, and I understand less about it than usual,
so I hope I'm not garbling anything when I impose the standard format
of "feature definition, then availability":
The ARMv6 architecture (not to be confused with product family ARM6)
uses physically addressed cache, solving many cache aliasing problems
and reducing context switch overhead. Unaligned and mixed-endian data
access is supported. This architecture includes the first version of
Thumb technology.
.
This feature is not guaranted by the architecture baseline, but is
available for newer armel machines in the ARM11 product family,
including ARM1136J(F)-S, ARM1156T2(F)-S, ARM1176JZ(F)-S,
ARM1136EJ(F)-S, and ARM11MPCore processors. Boards include the
Raspberry Pi model 1 and Raspberry Pi Zero.
Well, at least it's come out shorter for once.
>
> Package: armv6k-support
> Multi-Arch: foreign
> Architecture: armel
> Pre-Depends: isa-support (= ${binary:Version})
> Description: prevent installation on processors without required armv6k instructions
> This is a mostly dummy package, whose only purpose is to detect the presence
> of armv6k. It refuses to install on inadequate processors, thus allowing
> specifying such a requirement as a dependency.
> .
> This architecture is available the newer armel machine like
> for instance Raspberry Pi, but not guaranted by architecture
> baseline.
> .
> This a subarchitecture of armv6 adding SMP (Symmetric multiprocessing)
> instruction set, and Thread Local Storage instruction.
> .
> This architecture is available the newer armel machine like
> for instance Raspberry Pi, but not guaranted by architecture
> baseline. This architecture is available since ARM11 product
> family and include armv6k instruction set.
> Boards include the Raspberry Pi model 1 and
> Raspberry Pi Zero.
Lots of repetition that can be compressed here. From the top:
Description: CPU feature checking - require ARMv6k
The packages in the isa-support family can be used to probe for
microprocessor Instruction Set Architecture features such as SSE3. By
refusing to install on a machine that lacks particular required features,
they allow instruction set requirements to be handled in terms of package
dependencies.
.
This is a mostly dummy package which checks for ARMv6k and refuses to
install on unsupported hardware.
.
ARMv6k is a subarchitecture of ARMV6 adding Symmetric MultiProcessing
and Thread Local Storage instruction sets.
.
This feature is not guaranted by the architecture baseline, but is
available for newer armel machines in the ARM11 product family; boards
include the Raspberry Pi model 1 and Raspberry Pi Zero.
> Package: armv7-support
> Multi-Arch: foreign
> Architecture: armel
> Pre-Depends: isa-support (= ${binary:Version})
> Description: prevent installation on processors without required armv7 instructions
> This is a mostly dummy package, whose only purpose is to detect the presence
> of armv7. It refuses to install on inadequate processors, thus allowing
> specifying such a requirement as a dependency.
> .
As above (substituting in "ARMv7").
> This architecture is available the newer armel machine like
> for instance amrhf supported cpu, but not guaranted by architecture
> baseline.
Is this saying "ARMv7 is available for any CPU running armel that could
also support running armhf", or what?
> .
> This architecture includes Thumb-2 technology, adding
> 32-bit instructions into compressed Thumb mode.
(Goes and researches it, realises that "thumb" isn't an initialism,
it's just a pun on "compact ARM extension"...)
> .
> This architecture is available since Cortex-A product
> family including Cortex-A5, Cortex-A7,
> Cortex-A8, Cortex-A9, Cortex-A12, Cortex-A15 and Cortex-A17
> processors. Boards include the Raspberry Pi 2.
> This architecture should not be confused
> with product family ARM7.
So, fingers crossed that I'm not garbling this:
ARMv7 (not to be confused with product family ARM7) includes Thumb-2
technology, adding 32-bit instructions into compressed Thumb mode.
This feature is not guaranted by the architecture baseline, but is
available for newer armel machines (including CPUs that support armhf)
since the Cortex-A product family, including Cortex-A5, Cortex-A7,
Cortex-A8, Cortex-A9, Cortex-A12, Cortex-A15, and Cortex-A17
processors. Boards include the Raspberry Pi 2.
>
> Package: armv8-support
> Multi-Arch: foreign
> Architecture: armel armhf
> Pre-Depends: isa-support (= ${binary:Version})
> Description: prevent installation on processors without required armv8 instructions
> This is a mostly dummy package, whose only purpose is to detect the presence
> of armv8. It refuses to install on inadequate processors, thus allowing
> specifying such a requirement as a dependency.
> .
As above.
> This architecture is available the newer armel machine like
> for instance armhf port, but not guaranted by architecture
> baseline.
Is this saying something *different* from the ARMv7 one? If so, what?
> .
> This architecture is available since Cortex-A product
> family including Cortex-A32 and all arm64
> processors. Boards include the Raspberry Pi 3 and Raspberry Pi 4.
> This architecture should not be confused with product family ARM8.
You've skipped the "what good is ARMv8?" section, so I'll need to come
back to this.
ARMv8 (not to be confused with product family ARM8) has $TODO
.
This feature is not guaranted by the architecture baseline, but is
available for newer armel machines (including CPUs that support armhf)
since the Cortex-A product family, including Cortex-A32, as well as
all arm64 processors. Boards include the Raspberry Pi 3 and 4.
>
> Package: vfp-support
> Multi-Arch: foreign
> Architecture: armel
> Pre-Depends: isa-support (= ${binary:Version})
> Description: prevent installation on processors without required vfp instructions
> This is a mostly dummy package, whose only purpose is to detect the presence
> of vfp. It refuses to install on inadequate processors, thus allowing
> specifying such a requirement as a dependency.
As above.
> .
> VFP (Vector Floating Point) technology is a floating-point unit (FPU)
> coprocessor extension to the ARM architecture.
> This FPU provides single-precision and double-precision floating-point computation
> fully compliant with the ANSI/IEEE Std 754-1985.
Now it's skipping the "what has this feature?" part, and when it says
"this FPU", it's not clear what it means - later package descriptions
use the same phrase while talking about a different feature.
VFP (Vector Floating Point) technology is a floating-point unit (FPU)
coprocessor extension to the ARM architecture. It provides single- and
double-precision floating-point computation fully compliant with the
ANSI/IEEE Std 754-1985.
.
This feature is available $TODO
It might also want a VFPv1 line explaining that it provides eight
32-bit FPU registers, or whatever. Mind you, all the sources I can
find say that VFPv1 is officially obsolete, so how is it ever an
issue? Maybe it needs to say something about there being obscure
architectures that replace it with a cut-down version, and this
package just checks it isn't being installed on one of those?
>
> Package: vfpv2-support
> Multi-Arch: foreign
> Architecture: armel
> Pre-Depends: isa-support (= ${binary:Version})
> Description: prevent installation on processors without required vfpv2 instructions
> This is a mostly dummy package, whose only purpose is to detect the presence
> of vfpv2. It refuses to install on inadequate processors, thus allowing
> specifying such a requirement as a dependency.
> .
> VFP (Vector Floating Point) technology is a floating-point unit (FPU)
> coprocessor extension to the ARM architecture.
> This FPU provides single-precision and double-precision floating-point computation
> fully compliant with the ANSI/IEEE Std 754-1985.
> .
> VFPv2 has 16 64-bit FPU registers.
As above with the extra sentence about VFPv2, plus something like
This feature is available in the ARMv5TE, ARMv5TEJ, and ARMv6
architectures.
> Package: vfpv3-support
> Multi-Arch: foreign
> Architecture: armel
> Pre-Depends: isa-support (= ${binary:Version})
> Description: prevent installation on processors without required vfpv3 instructions
> This is a mostly dummy package, whose only purpose is to detect the presence
> of vfpv3. It refuses to install on inadequate processors, thus allowing
> specifying such a requirement as a dependency.
> .
> VFP (Vector Floating Point) technology is a floating-point unit (FPU)
> coprocessor extension to the ARM architecture.
> This FPU provides single-precision and double-precision floating-point computation
> fully compliant with the ANSI/IEEE Std 754-1985.
> .
> VFPv3 is backwards compatible with VFPv2, except that
> it cannot trap floating-point exceptions.
> VFPv3 has 32 64-bit FPU registers as standard, adds VCVT instructions
> to convert between scalar,
> float and double, adds immediate mode to
> VMOV such that constants can be loaded into FPU registers.
Why would we care about backwards compatibility?
VFP (Vector Floating Point) technology is a floating-point unit (FPU)
coprocessor extension to the ARM architecture. It provides single- and
double-precision floating-point computation fully compliant with the
ANSI/IEEE Std 754-1985.
.
VFPv3 has 32 64-bit FPU registers as standard, adds VCVT instructions
to convert between scalar, float, and double, and adds immediate mode to
VMOV, allowing constants to be loaded into FPU registers.
.
This feature is available on most Cortex-A8 and A9 ARMv7 processors.
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
Reply to: