Re: ioperm(2): confusing terminology

[Alejandro Colomar <alx@kernel.org>]

[-- Attachment #1: Type: text/plain, Size: 3423 bytes --]

Hi astian,

> Date: 2026-09-12 22:00:57+0000
> From: astian <astian@memeware.net>
>
> ioperm(2) says:
> 
>   int ioperm(unsigned long from, unsigned long num, int turn_on);
> 
>   ioperm() sets the port access permission bits for the calling thread
>   for num bits starting from port address from.  If turn_on is nonzero,
>   then permission for the specified bits is enabled; otherwise it is
>   disabled. [...]
> 
> The use of "bits" here is confusing/sloppy.
> 
> ioperm is supposed to enable or disable permission to access IO ports
> for the calling thread.  In this API, the "permission bit" (singular) is
> really "turn_on": 0 to disable access, non-zero to enable.  However this
> description refers also "num bits starting from port address from" and
> "the specified bits".  That seems to suggest that IO ports somehow refer
> to "bits" and this API controls access permission to them, which is
> bewildering.
> 
> Searching around I have seen that other versions of this manpage used to
> say "bytes" instead of "bits", which is only slightly less bewildering.
> Ports/addresses in the IO space refer neither to bits nor to bytes per
> se, they are an abstract interface, like a syscall number/index.
> (Architecturally, in some cases, these indices may in fact map to
> processor registers which may in fact be portions of a contiguous
> internal memory, so in some cases one could correctly say that the ports
> refer to "bytes" in such memory, but this is obviously all very
> low-level and microarchitecture-specific.  I think being aware of such
> details actually makes this description more confusing.)
> 
> Apparently the reason for this confusing description is that for Linux
> ioperm is a syscall and the kernel implements this syscall using a
> bitmap with 1 bit (permitted/denied) for each port, in a contiguous
> sequence.  See ksys_ioperm in "arch/x86/kernel/ioport.c".
> 
> Thus "num bits starting from port address from" actually refers to the
> bits of that bitmap: the bits [from, from+num) are set according to
> turn_on.
> 
> This kind of implicit reference to implementation details is wicked.
> 
> Suggested change:
> 
>   ioperm() sets the calling thread's access permission for num ports
>   starting from port address from.  If turn_on is nonzero, then
>   permission for the specified ports is enabled; otherwise it is
>   disabled. [...]

Hmmm, sounds reasonable.  Do you want to send a patch?  Or should
I write it?  (I don't mind; just asking in case you want to do it.)

> PS: Oh, also, maybe the title should say "set input/output port
> permissions" instead of "set port input/output permissions".

Same here.

BTW, the manual page also says:

     This  call  is  mostly for the i386 architecture.  On many
     other architectures it does not exist or will  always  re‐
     turn an error.

Is this still true?

Another issue:

     EIO    (on PowerPC) This call is not supported.

Is this really true?  Where this is not supported, I expect ENOSYS.

And yet another thing: should we document the parameters as being
uintptr_t instead of unsigned long?  They are the same exact type
always, AFAIK.  Or is there any system where they aren't?  If they are
the same, uintptr_t will better document that they are addresses.


Have a lovely night!
Alex

-- 
<https://www.alejandro-colomar.es>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]