Page MenuHomeFreeBSD

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

Authored by ziaee on Thu, Nov 13, 3:18 AM.
Tags
None
Referenced Files
Unknown Object (File)
Mon, Dec 1, 9:19 AM
Unknown Object (File)
Sun, Nov 30, 8:05 AM
Unknown Object (File)
Fri, Nov 28, 3:20 PM
Unknown Object (File)
Wed, Nov 26, 7:23 AM
Unknown Object (File)
Wed, Nov 19, 5:19 PM
Unknown Object (File)
Mon, Nov 17, 8:37 AM
Unknown Object (File)
Mon, Nov 17, 8:36 AM
Unknown Object (File)
Fri, Nov 14, 11:41 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

  1. 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.
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!

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

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.

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.

usr.sbin/zzz/zzz.8
45

What about this?