apm.4: Remove a stale manual and update mlink
Needs ReviewPublic
Actions

Authored by ziaee on Thu, Nov 13, 3:18 AM.

Details

Reviewers

emaste
imp
jhb
pauamma_gundo.com

Group Reviewers

manpages

Summary

This manual described a driver for pre-acpi bios, which was removed in

The acpi interface provides the same ioctls, and support for the

apm(8) utility. Since we do still have a /dev/apm, relink acpi.4 there.
Therefore, do not put apm.4 in ObsoleteFiles.inc for removal.

Since acpi provides these interfaces, it's just the manuals that could
use some love, or should the code paths be removed for e.g. apm -z
and powerd -s apm? If so, these seem pretty well ifdefed, can I try to
do it?

MFC after: 2 days
Reported by: emaste, jhb
Fixes: 8c576a279ed5 (Remove APM BIOS support)

Diff Detail

Repository

rG FreeBSD src repository

Lint

Lint Skipped

Unit

Tests Skipped

Build Status

Buildable 68610
Build 65493: arc lint + arc unit

Event Timeline

ziaee requested review of this revision.Thu, Nov 13, 3:18 AM

ziaee created this revision.

Harbormaster completed remote builds in B68586: Diff 166338.Thu, Nov 13, 3:18 AM

English and markup both LGTM.

This revision is now accepted and ready to land.Thu, Nov 13, 3:25 AM

Thanks pauamma! You've been really crushing it finding typos that I sincerely read over and didn't notice lately!

emaste added inline comments.Thu, Nov 13, 3:33 AM

share/man/man4/Makefile
658–659	I don't think we should add this MLINK since acpi.4 makes no reference to apm.

Would it fix it if we add a FILES section to acpi.4 showing the device
nodes?

This revision now requires review to proceed.Thu, Nov 13, 3:47 AM

Harbormaster completed remote builds in B68587: Diff 166339.Thu, Nov 13, 3:47 AM

In D53724#1226655, @ziaee wrote:

Would it fix it if we add a FILES section to acpi.4 showing the device
nodes?

We might also need to move the interfaces that were documented in apm.4 to there.

Copy ioctls and event from apm.4, tweaking very slightly so it looks
intentional, and re-aligning list widths as well for that effect.

This is way above my head honestly and I don't know if this is correct.

Harbormaster completed remote builds in B68610: Diff 166377.Thu, Nov 13, 5:02 PM

ziaee added inline comments.Thu, Nov 13, 5:04 PM

share/man/man4/acpi.4
605	This is where I found the ioctls when I git grepped
608	I changed these to Dvs because they're ioctls, right?
679	Unrelated, arm64 has acpi now too, right?

Can I do anything with this or push it? I want to have 15.0R not have a doc that says it's going to be removed in 5 years ago at the top.

Hmmm, I wonder if what might be better is to rework the existing apm.4 manpage to say it is an interface (instead of a driver), but not merge all its content over into acpi.4. It's more that this is a way to describe an API than a device driver. There would be no real SYNOPSIS in this case in the classic sense (we don't really have a model for a SYNOPSIS for something that is an abstract interface as opposed to a foo.ko you can load). That is, you would take the existing apm.4, and make the following changes:

.Dt "Power management interface"

SYNOPSIS - remove (there's nothing to really put here)

.Sh DESCRIPTION
.Nm
is an interface to power management on i386 and amd64.
This interface was originally designed to support the
Advanced Power Management (APM) BIOS extension on i386.
However,
the interface is now implemented by
.Xr acpi 4.
...

Then only keep bullets 4 and 5 from the list, but don't make them part of a bullet list, just separate paragraphs. There's a separate issue that 4 is missing some commands, and in particular the list from bullet 5 should be a nested list under a description of APMIO_NEXTEVENT instead. Also, there manpage needs a .Sh FILES section that lists /dev/apm.

share/man/man4/acpi.4
605	The old text is more correct. <machine/apm_bios.h> is the public header to use for these. This header is just an implementation detail so that it is shared between amd64 and i386.