diff --git a/gfxutil.1 b/gfxutil.1 index 265a51e..52e0cc8 100644 --- a/gfxutil.1 +++ b/gfxutil.1 @@ -1,79 +1,204 @@ -.\"Modified from man(1) of FreeBSD, the NetBSD mdoc.template, and mdoc.samples. -.\"See Also: -.\"man mdoc.samples for a complete listing of options -.\"man mdoc for the short list of editing options -.\"/usr/share/misc/mdoc.template -.Dd 14.12.07 \" DATE -.Dt gfxutil 1 \" Program name and manual section number -.Os Darwin -.Sh NAME \" Section Header - required - don't modify -.Nm gfxutil, -.\" The following lines are read in generating the apropos(man -k) database. Use only key -.\" words here as the database is built based on the words here and in the .ND line. -.Nm Other_name_for_same_program(), -.Nm Yet another name for the same program. -.\" Use .Nm macro to designate other names for the documented program. -.Nd This line parsed for whatis database. -.Sh SYNOPSIS \" Section Header - required - don't modify +.\" This document was created by modifying the template from the FreeBSD +.\" Documentation Project Handbook, Chapter 11, section 11.4.1. +.\" +.\" Credit is also given to the following links for their invaluable help in +.\" understanding the mdoc syntax: +.\" * http://manpages.bsd.lv/mdoc.html +.\" * https://www.mankier.com/7/mdoc +.\" +.\" The following tool was invaluable for syntax highlighting: +.\" * https://roperzh.github.io/grapse/ +.Dd August 10, 2024 +.Dt GFXUTIL 1 +.Os +.Sh NAME +.Nm gfxutil +.Nd "Device Properties conversion tool" +.Sh SYNOPSIS .Nm -.Op Fl abcd \" [-abcd] -.Op Fl a Ar path \" [-a path] -.Op Ar file \" [file] -.Op Ar \" [file ...] -.Ar arg0 \" Underlined argument - use .Ar anywhere to underline -arg2 ... \" Arguments -.Sh DESCRIPTION \" Section Header - required - don't modify -Use the .Nm macro to refer to your program throughout the man page like such: +.Oo +.Op Fl l +.Op Fl m +.Op Fl n +.Op Fl s +.Op Fl v +.Op Fl i Ar fmt +.Op Fl o Ar fmt +.Oc +.Oo +.Oo +.Fl a +| +.Fl c Op Ar efi_path +| +.Fl d Ar path Ar prop +| +.Fl f Ar name +| +.Fl h +| +.Fl p +| +.Fl t +.Oc +| +.Ar infile Ar outfile +| +.Ar efi_path +.Oc +.Sh DESCRIPTION +The .Nm -Underlining is accomplished with the .Ar macro like this: -.Ar underlined text . -.Pp \" Inserts a space -A list of items with descriptions: -.Bl -tag -width -indent \" Begins a tagged list -.It item a \" Each item preceded by .It macro -Description of item a -.It item b -Description of item b -.El \" Ends the list +command can be used for listing and finding PCI and APCI device paths in the +IODeviceTree plane; outputting an EFI device path from an +.Ql ioreg +path and property; converting an EFI device path to text or hex from binary, +nvram, hex, or text input; and converting a property list. +.Ss COMMAND FLAGS +The command flags are the first input(s) to the +.Nm +command: +.Bl -tag -width Ds +.It Fl l +Causes +.Nm +to output a shorter text representation of the display node, where applicable. +.It Fl m +Lets +.Nm +know that shorter text representations of the device node should not be used. +.It Fl n +Tells +.Nm +to automatically detect numeric format from binary data. +.It Fl s +Tells +.Nm +to automatically detect string format from binary data. +.It Fl v +Enables verbose mode. +.It Fl i Ar fmt +Specifies the +.Ar infile +type, one of: +.Bl -bullet -width Ds +.It +.Ql bin +.It +.Ql hex +.It +.Ql xml +.El +.Pp +The default is +.Ql hex . +.It Fl o Ar fmt +Specifies the +.Ar outfile +type, one of: +.Bl -bullet -width Ds +.It +.Ql bin +.It +.Ql hex +.It +.Ql xml +.El +.Pp +The default is +.Ql xml . +.El +.Ss COMMAND ACTIONS +The next input(s) to +.Nm +represent the command action: +.Bl -tag -width Ds +.It Fl a +Shows the +.Nm +version. +.It Xo +.Fl c Op Ar efi_path , +.Ar efi_path +.Xc +Converts an EFI device path to text or hex. +.Pp +If +.Ar efi_path +is not specified, +.Nm +will take its input from +.Ql stdin +(needs to be piped in). +.Pp +The EFI path can be in the following formats: +.Bl -tag -width Ds +.It Binary +This format can only be used as an input and needs to be piped in from +.Ql stdin . +.It NVRAM +This format can only be used as an input. +The input comes from the +.Ql nvram +command and starts with a +.Ql % . +.It Hex +Hex digits with no spaces. +This format can be used for both input and output. +.It Text +A text representation of an EFI device path. +This format can be used for both input and output. +.El +.It Fl d Ar path Ar prop +Converts an +.Ql ioreg +path and property to an EFI device path. +.It Fl f Ar name +Finds device paths for devices matching +.Ar name +in the IODeviceTree plane. +.It Fl h +Prints a summary of +.Nm +flags and commands. +.It Fl p +Lists all device paths for PCI devices in the IODeviceTree plane. +.It Fl t +Lists all device paths for PCI and ACPI devices in the IODeviceTree plane in +tree order. +.It Ar infile Ar outfile +Converts a property list, +.Ar infile , +to +.Ar outfile +using the formats specified in the +.Fl i Ar fmt +and +.Fl o Ar fmt +flags. +.El +.Sh EXAMPLES +A handful of +.Nm +functionalities are demonstrated below. +.Pp +Listing the device paths for all PCI devices in the IODeviceTree plane: +.Pp +.Dl % gfxutil +.Pp +Getting a summary of the tool's actions: +.Pp +.Dl % gfxutil -h +.Pp +Find the device path for the +.Ql HDEF +device: +.Pp +.Dl % gfxutil -f HDEF .Pp -A list of flags and their descriptions: -.Bl -tag -width -indent \" Differs from above in tag removed -.It Fl a \"-a flag as a list item -Description of -a flag -.It Fl b -Description of -b flag -.El \" Ends the list +Get the EFI device path for the boot device: .Pp -.\" .Sh ENVIRONMENT \" May not be needed -.\" .Bl -tag -width "ENV_VAR_1" -indent \" ENV_VAR_1 is width of the string ENV_VAR_1 -.\" .It Ev ENV_VAR_1 -.\" Description of ENV_VAR_1 -.\" .It Ev ENV_VAR_2 -.\" Description of ENV_VAR_2 -.\" .El -.Sh FILES \" File used or created by the topic of the man page -.Bl -tag -width "/Users/joeuser/Library/really_long_file_name" -compact -.It Pa /usr/share/file_name -FILE_1 description -.It Pa /Users/joeuser/Library/really_long_file_name -FILE_2 description -.El \" Ends the list -.\" .Sh DIAGNOSTICS \" May not be needed -.\" .Bl -diag -.\" .It Diagnostic Tag -.\" Diagnostic informtion here. -.\" .It Diagnostic Tag -.\" Diagnostic informtion here. -.\" .El -.Sh SEE ALSO -.\" List links in ascending order by section, alphabetically within a section. -.\" Please do not reference files that do not exist without filing a bug report -.Xr a 1 , -.Xr b 1 , -.Xr c 1 , -.Xr a 2 , -.Xr b 2 , -.Xr a 3 , -.Xr b 3 -.\" .Sh BUGS \" Document known, unremedied bugs -.\" .Sh HISTORY \" Document history if command behaves in a unique manner \ No newline at end of file +.Dl % gfxutil -d IODeviceTree:/chosen boot-device-path +.Sh SEE ALSO +.Xr ioreg 1 , +.Xr nvram 1