Created new gfxutil.1

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
+.Dl % gfxutil -d IODeviceTree:/chosen boot-device-path
+.Sh SEE ALSO
+.Xr ioreg 1 ,
+.Xr nvram 1