[PATCH 0/5] Various doc fixes and test code explanation

[PATCH 0/5] Various doc fixes and test code explanation

[Glenn Washburn]

Patch #1 is a small spelling error or typo and could be folded into patch
#2, or some other patch of trivial spelling fixes, not sure which is
preferred. Patch #2 was created via a cursory read through. There are
more improvments to be had and I think some parts where I was unsure of
the meaning. The rest of the patches are self-explanatory.

Glenn

Glenn Washburn (5):
  misc: Fix spelling mistakes
  docs: Fix spelling, grammatical and usage issues with new Porting
    section
  docs: Add note and explanation that the privileged user is required
    for properly running the tests
  docs: Reorganize test section and add section on writing tests
  INSTALL: Make note that linux kernel 6.12.x or earlier is needed

 INSTALL              |   8 ++-
 docs/grub-dev.texi   | 168 ++++++++++++++++++++++++++++---------------
 docs/grub.texi       |   2 +-
 util/grub-mkrescue.c |   2 +-
 4 files changed, 116 insertions(+), 64 deletions(-)

-- 
2.34.1


_______________________________________________
Grub-devel mailing list
Grub-devel@gnu.org
https://lists.gnu.org/mailman/listinfo/grub-devel

[PATCH 1/5] misc: Fix spelling mistakes

[Glenn Washburn]

Signed-off-by: Glenn Washburn <development@efficientek.com>
---
 util/grub-mkrescue.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/util/grub-mkrescue.c b/util/grub-mkrescue.c
index 6dc71a8a1628..ad47e4808ae5 100644
--- a/util/grub-mkrescue.c
+++ b/util/grub-mkrescue.c
@@ -469,7 +469,7 @@ main (int argc, char *argv[])
   argp_argv[0] = argv[0];
   argp_argc = 1;
 
-  /* argp doesn't allow us to catch unknwon arguments,
+  /* argp doesn't allow us to catch unknown arguments,
      so catch them before passing to argp
    */
   {
-- 
2.34.1


_______________________________________________
Grub-devel mailing list
Grub-devel@gnu.org
https://lists.gnu.org/mailman/listinfo/grub-devel

[PATCH 2/5] docs: Fix spelling, grammatical and usage issues with new Porting section

[Glenn Washburn]

There are some other fixes outside of this section as well.

Signed-off-by: Glenn Washburn <development@efficientek.com>
---
 docs/grub-dev.texi | 114 ++++++++++++++++++++++-----------------------
 docs/grub.texi     |   2 +-
 2 files changed, 58 insertions(+), 58 deletions(-)

diff --git a/docs/grub-dev.texi b/docs/grub-dev.texi
index 62ad43c9db80..9a2e9d90624f 100644
--- a/docs/grub-dev.texi
+++ b/docs/grub-dev.texi
@@ -900,26 +900,26 @@ is to be run in a GDB session running with the @file{gdb_grub} GDB script.
 @node Porting
 @chapter Porting
 
-GRUB2 is designed to be easily portable accross platforms. But because of the
+GRUB2 is designed to be easily portable across platforms. But because of the
 nature of bootloader every new port must be done separately. Here is how I did
-MIPS (loongson and ARC) and Xen ports. Note than this is more of suggestions,
-not absolute truth.
+MIPS (loongson and ARC) and Xen ports. Note that this is more of a suggestion,
+and not absolute truth.
 
-First of all grab any architecture specifications you can find in public
-(please avoid NDA).
+First of all, grab any architecture specifications you can find in the public
+domain (please avoid NDA).
 
 First stage is ``Hello world''. I've done it outside of GRUB for simplicity.
 Your task is to have a small program which is loadable as bootloader and
-clearly shows its presence to you. If you have easily accessible console
-you can just print a message. If you have a mapped framebuffer you know address
+clearly shows its presence to you. If you have an easily accessible console
+you can just print a message. If you have a mapped framebuffer you know the address
 of, you can draw a square. If you have a debug facility, just hanging without
-crashing might be enough. For the first stage you can choose to load the
-bootloader across the network since format for network image is often easier
+crashing might be enough. For the first stage, you can choose to load the
+bootloader across the network since the format for a network image is often easier
 than for local boot and it skips the need of small intermediary stages and
-nvram handling. Additionally you can often have a good idea of the needed
-format by running ``file'' on any netbootable executable for given platform.
+nvram handling. Additionally, you can often have a good idea of the needed
+format by running ``file'' on any netbootable executable for the given platform.
 
-This program should probably have 2 parts: an assembler and C one. Assembler one
+This program should probably have 2 parts: an assembler and C one. The assembler one
 handles BSS cleaning and other needed setup (on some platforms you may need
 to switch modes or copy the executable to its definitive position). So your code
 may look like (x86 assembly for illustration purposes)
@@ -961,12 +961,12 @@ Sometimes you need a third file: assembly stubs for ABI-compatibility.
 
 Once this file is functional it's time to move it into GRUB2. The startup
 assembly file goes to grub-core/kern/$cpu/$platform/startup.S. You should also
-include grub/symbol.h and replace call to entry point with call to
+include grub/symbol.h and replace the call to entry point with call to
 EXT_C(grub_main). The C file goes to grub-core/kern/$cpu/$platform/init.c
 and its entry point is renamed to void grub_machine_init (void). Keep final
-infinite loop for now. Stubs file if any goes to
+infinite loop for now. Stub files if any goes to
 grub-core/kern/$cpu/$platform/callwrap.S. Sometimes either $cpu or $platform
-is dropped if file is used on several cpus respectivelyplatforms.
+is dropped if file is used on several cpus respectively or platforms.
 Check those locations if they already have what you're looking for.
 
 Then modify in configure.ac the following parts:
@@ -984,10 +984,10 @@ esac
 @end example
 
 Sometimes CPU have additional architecture names which don't influence booting.
-You might want to have some canonical name to avoid having bunch of identical
+You might want to have some canonical name to avoid having a bunch of identical
 platforms with different names.
 
-NOTE: it doesn't influence compile optimisations which depend solely on
+NOTE: It doesn't influence compile optimisations which depend solely on
 chosen compiler and compile options.
 
 @example
@@ -1049,7 +1049,7 @@ AM_CONDITIONAL([COND_powerpc_ieee1275], [test x$target_cpu = xpowerpc -a x$platf
 @end example
 
 Next stop is gentpl.py. You need to add your platform to the list of supported
-ones (sorry that this list is duplicated):
+ones (unfortunately, this list is duplicated):
 
 @example
 GRUB_PLATFORMS = [ "emu", "i386_pc", "i386_efi", "i386_qemu", "i386_coreboot",
@@ -1059,21 +1059,21 @@ GRUB_PLATFORMS = [ "emu", "i386_pc", "i386_efi", "i386_qemu", "i386_coreboot",
                    "mips_qemu_mips", "s390_mainframe" ]
 @end example
 
-You may also want already to add new platform to one or several of available
+Now you may also want to add a new platform to one or several of available
 groups. In particular we always have a group for each CPU even when only
 one platform for given CPU is available.
 
 Then comes grub-core/Makefile.core.def. In the block ``kernel'' you'll need
 to define ldflags for your platform ($cpu_$platform_ldflags). You also need to
-declare startup asm file ($cpu_$platform_startup) as well as any other files
-(e.g. init.c and callwrap.S) (e.g. $cpu_$platform = kern/$cpu/$platform/init.c).
-At this stage you will also need to add dummy dl.c and cache.S with functions
+declare a startup asm file ($cpu_$platform_startup) as well as any other files,
+like init.c or callwrap.S (e.g. $cpu_$platform = kern/$cpu/$platform/init.c).
+At this stage, you will also need to add a dummy dl.c and cache.S with functions
 grub_err_t grub_arch_dl_check_header (void *ehdr), grub_err_t
 grub_arch_dl_relocate_symbols (grub_dl_t mod, void *ehdr) (dl.c) and
 void grub_arch_sync_caches (void *address, grub_size_t len) (cache.S). They
 won't be used for now.
 
-You will need to create directory include/$cpu/$platform and a file
+You will need to create a directory include/$cpu/$platform and a file
 include/$cpu/types.h. The latter following this template:
 
 @example
@@ -1097,7 +1097,7 @@ include/$cpu/types.h. The latter following this template:
 You will also need to add a dummy file to datetime and setjmp modules to
 avoid any of it having no files. It can be just completely empty at this stage.
 
-You'll need to make grub-mkimage.c (util/grub_mkimage.c) aware of the needed
+You'll need to make grub-mkimage (in util/grub_mkimage.c) aware of the needed
 format. For most commonly used formats like ELF, PE, aout or raw the support
 is already present and you'll need to make it follow the existant code paths
 for your platform adding adjustments if necessary. When done compile:
@@ -1108,47 +1108,47 @@ for your platform adding adjustments if necessary. When done compile:
 make > /dev/null
 @end example
 
-And create image
+And create an image:
 
 @example
 ./grub-mkimage -d grub-core -O $format_id -o test.img
 @end example
 
-And it's time to test your test.img.
+And now it's time to test your test.img.
 
-If it works next stage is to have heap, console and timer.
+If it works, the next stage is to have a heap, console and timer.
 
 To have the heap working you need to determine which regions are suitable for
-heap usage, allocate them from firmware and map (if applicable). Then call
-grub_mm_init_region (void *start, grub_size_t s) for every of this region.
-As a shortcut for early port you can allocate right after _end or have
-a big static array for heap. If you do you'll probably need to come back to
+heap usage, allocate them from the firmware and map them, if applicable.
+Then call grub_mm_init_region (void *start, grub_size_t s) for each region.
+As a shortcut for an early port, you can allocate right after _end or have
+a big static array for heap. If you do, you'll probably need to come back to
 this later. As for output console you should distinguish between an array of
-text, terminfo or graphics-based console. Many of real-world examples don't
+text, terminfo or graphics-based console. Many real-world examples don't
 fit perfectly into any of these categories but one of the models is easier
-to be used as base. In second and third case you should add your platform to
+to be used as base. In the second and third case, you should add your platform to
 terminfokernel respectively videoinkernel group. A good example of array of
-text is i386-pc (kern/i386/pc/init.c and term/i386/pc/console.c).
-Of terminfo is ieee1275 (kern/ieee1275/init.c and term/ieee1275/console.c).
-Of video is loongson (kern/mips/loongson/init.c). Note that terminfo has
+text is i386-pc (kern/i386/pc/init.c and term/i386/pc/console.c),
+of terminfo is ieee1275 (kern/ieee1275/init.c and term/ieee1275/console.c),
+and of video is loongson (kern/mips/loongson/init.c). Note that terminfo has
 to be inited in 2 stages: one before (to get at least rudimentary console
 as early as possible) and another after the heap (to get full-featured console).
-For the input there are string of keys, terminfo and direct hardware. For string
-of keys look at i386-pc (same files), for terminfo ieee1275 (same files) and for
-hardware loongson (kern/mips/loongson/init.c and term/at_keyboard.c).
+For the input, there is a string of keys (eg. i386-pc, same files), terminfo
+(ieee1275, same files), and hardware (loongson, see kern/mips/loongson/init.c
+and term/at_keyboard.c).
 
-For the timer you'll need to call grub_install_get_time_ms (...) with as sole
-argument a function returning a grub_uint64_t of a number of milliseconds
+For the timer, you'll need to call grub_install_get_time_ms (...) with the
+sole argument a function returning a grub_uint64_t number of milliseconds
 elapsed since arbitrary point in the past.
 
-Once these steps accomplished you can remove the inifinite loop and you should
+Once these steps are accomplished, you can remove the inifinite loop and you should
 be able to get to the minimal console. Next step is to have module loading
-working. For this you'll need to fill kern/$cpu/dl.c and kern/$cpu/cache.S
+working. For this, you'll need to fill kern/$cpu/dl.c and kern/$cpu/cache.S
 with real handling of relocations and respectively the real sync of I and D
 caches. Also you'll need to decide where in the image to store the modules.
 Usual way is to have it concatenated at the end. In this case you'll need to
 modify startup.S to copy modules out of bss to let's say ALIGN_UP (_end, 8)
-before cleaning out bss. You'll probably find useful to add total_module_size
+before cleaning out bss. You'll probably find it useful to add total_module_size
 field to startup.S. In init.c you need to set grub_modbase to the address
 where modules can be found. You may need grub_modules_get_end () to avoid
 declaring the space occupied by modules as usable for heap. You can test modules
@@ -1164,9 +1164,9 @@ Once this works, you should think of implementing disk access. Look around
 disk/ for examples.
 
 Then, very importantly, you probably need to implement the actual loader
-(examples available in loader/)
+(examples available in loader/).
 
-Last step to have minimally usable port is to add support to grub-install to
+The last step to have a minimally usable port is to add support to grub-install to
 put GRUB in a place where firmware or platform will pick it up.
 
 Next steps are: filling datetime.c, setjmp.S, network (net/drivers),
@@ -1175,15 +1175,15 @@ video (video/), halt (lib/), reboot (lib/).
 Please add your platform to Platform limitations and Supported kernels chapter
 in user documentation and mention any steps you skipped which result in reduced
 features or performance. Here is the quick checklist of features. Some of them
-are less important than others and skipping them is completely ok, just needs
+are less important than others and skipping them is completely ok, it just needs
 to be mentioned in user documentation.
 
 Checklist:
 @itemize
-@item Is heap big enough?
-@item Which charset is supported by console?
-@item Does platform have disk driver?
-@item Do you have network card support?
+@item Is the heap big enough?
+@item Which charset is supported by the console?
+@item Does the platform have disk driver?
+@item Is there network card support?
 @item Are you able to retrieve datetime (with date)?
 @item Are you able to set datetime (with date)?
 @item Is serial supported?
@@ -1209,16 +1209,16 @@ GRUB?
 @node Error Handling
 @chapter Error Handling
 
-Error handling in GRUB 2 is based on exception handling model. As C language
+Error handling in GRUB 2 is based on exception handling model. As the C language
 doesn't directly support exceptions, exception handling behavior is emulated
-in software. 
+in software.
 
-When exception is raised, function must return to calling function. If calling
+When an exception is raised, the function must return to the calling function. If the calling
 function does not provide handling of the exception it must return back to its
-calling function and so on, until exception is handled. If exception is not
-handled before prompt is displayed, error message will be shown to user.
+calling function and so on, until the exception is handled. If the exception is not
+handled before a prompt is displayed, error message will be shown to user.
 
-Exception information is stored on @code{grub_errno} global variable. If
+Exception information is stored in the @code{grub_errno} global variable. If
 @code{grub_errno} variable contains value @code{GRUB_ERR_NONE}, there is no active
 exception and application can continue normal processing. When @code{grub_errno} has
 other value, it is required that application code either handles this error or
diff --git a/docs/grub.texi b/docs/grub.texi
index d2fa055c366e..0d3dbfa6564d 100644
--- a/docs/grub.texi
+++ b/docs/grub.texi
@@ -2943,7 +2943,7 @@ Heavily limited platforms:
 Lightly limited platforms:
 
 @itemize
-@item *-xen: limited only by adress space and RAM size.
+@item *-xen: limited only by address space and RAM size.
 @item i386-qemu: kernel.img (.text + .data + .bss) is limited by 392704 bytes.
                  (core.img would be limited by ROM size but it's unlimited on qemu
 @item All EFI platforms: limited by contiguous RAM size and possibly firmware bugs
-- 
2.34.1


_______________________________________________
Grub-devel mailing list
Grub-devel@gnu.org
https://lists.gnu.org/mailman/listinfo/grub-devel

[PATCH 3/5] docs: Add note and explanation that the privileged user is required for properly running the tests

[Glenn Washburn]

Signed-off-by: Glenn Washburn <development@efficientek.com>
---
 docs/grub-dev.texi | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/docs/grub-dev.texi b/docs/grub-dev.texi
index 9a2e9d90624f..9d256145eaa0 100644
--- a/docs/grub-dev.texi
+++ b/docs/grub-dev.texi
@@ -495,6 +495,9 @@ These dependencies are currently documented in the
 @uref{https://git.savannah.gnu.org/cgit/grub.git/tree/INSTALL, INSTALL}
 file in the source repository. Once installed, the test suite can be started
 by running the @command{make check} command from the GRUB build directory.
+To properly run all the tests, the test suite must be run as the privileged
+user. For instance, the filesystem tests require creating and mounting the
+tested filessytems.
 
 @node Updating External Code
 @chapter Updating external code
-- 
2.34.1


_______________________________________________
Grub-devel mailing list
Grub-devel@gnu.org
https://lists.gnu.org/mailman/listinfo/grub-devel

[PATCH 4/5] docs: Reorganize test section and add section on writing tests

[Glenn Washburn]

Rename the main section to Tests and put the existing test section into
a subsection. A new subsection called "Writing tests" is added to give
a brief overview and make clear the difference in returning a SKIP code
versus a HARD ERROR code.

Signed-off-by: Glenn Washburn <development@efficientek.com>
---
 docs/grub-dev.texi | 55 ++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 51 insertions(+), 4 deletions(-)

diff --git a/docs/grub-dev.texi b/docs/grub-dev.texi
index 9d256145eaa0..51a0923ec319 100644
--- a/docs/grub-dev.texi
+++ b/docs/grub-dev.texi
@@ -77,7 +77,7 @@ This edition documents version @value{VERSION}.
 * Coding style::
 * Finding your way around::
 * Contributing Changes::
-* Setting up and running test suite::
+* Tests::
 * Updating External Code::
 * Debugging::
 * Porting::
@@ -485,8 +485,17 @@ If your intention is to just get started, please do not submit a inclusion
 request. Instead, please subscribe to the mailing list, and communicate first
 (e.g. sending a patch, asking a question, commenting on another message...).
 
+@node Tests
+@chapter Tests
+
+@menu
+* Setting up and running test suite::
+* Writing new tests::
+@end menu
+
+
 @node Setting up and running test suite
-@chapter Setting up and running test suite
+@section Setting up and running test suite
 
 GRUB is basically a tiny operating system with read support for many file
 systems and which has been ported to a variety of architectures. As such, its
@@ -496,8 +505,46 @@ These dependencies are currently documented in the
 file in the source repository. Once installed, the test suite can be started
 by running the @command{make check} command from the GRUB build directory.
 To properly run all the tests, the test suite must be run as the privileged
-user. For instance, the filesystem tests require creating and mounting the
-tested filessytems.
+user, for instance to run the filesystem tests, which require mounting
+filesystem images. Of course, virtualization or containers may be used, but
+this requires extra configuration outside the scope of this document.
+
+@node Writing new tests
+@section Writing new tests
+
+There are two kinds of tests in the GRUB test suite: native and non-native.
+Native tests are those which run on the build architecture and non-native
+run on the target architecture. The non-native tests are run in a QEMU
+virtual machine using the grub-shell script in tests/util. When writing a
+new test, first determine if it should run on the host or the target and
+then look at the existing tests as examples of how to they should be written.
+
+The GRUB test suite uses automake (@uref{https://www.gnu.org/software/automake/manual/automake.html#Tests, see documention here}). One thing of importance
+to note is that tests have 4 classes of return codes: SKIP (77), HARD ERROR
+(99), PASS (0), and FAIL (all other codes). A
+@uref{https://www.gnu.org/software/automake/manual/automake.html#index-test-skip, SKIP return code}
+should be returned when this test cannot be performed and thus should be
+skipped. Typically this is because the target does not support the test,
+such as the ohci USB test for the powerpc-ieee1275 target because there
+are no native drivers for that target. A
+@uref{https://www.gnu.org/software/automake/manual/automake.html#index-Distinction-between-errors-and-failures-in-testsuites, HARD ERROR return code}
+should be returned when a failure in something other than what is intended
+to be tested happens. This is commonly returned when the test cannot be
+properly run because of deficiencies in the test environment, eg. when
+testing the xfs filesystem, but the kernel has no support for mounting xfs
+volumes. A SKIP should never be returned for a HARD ERROR condition
+because at best the person running the test does not know if the test was
+skipped because it doesn't apply to the target or because the tester failed
+to setup the environment properly. At worst, the tester will believe that
+everything is okay without realizing that the tests are not covering all
+the code that it should.
+
+Keep portability in mind while creating a new tests so that the tests can be
+run on a variety of systems and shells. Do not use bashisms. Also try to avoid
+using utilities that would unecessarily add software dependencies. Sometimes
+this is unavoidable. Copy or adapt existing test implementations where feasible.
+If the test is native and requires root, make sure to check that the test is
+run with the root user and return HARD ERROR if it is not.
 
 @node Updating External Code
 @chapter Updating external code
-- 
2.34.1


_______________________________________________
Grub-devel mailing list
Grub-devel@gnu.org
https://lists.gnu.org/mailman/listinfo/grub-devel

[PATCH 5/5] INSTALL: Make note that linux kernel 6.12.x or earlier is needed

[Glenn Washburn]

Also, remove wording suggesting that tests may be skipped if prerequisites
are not installed. Tests should never be skipped because of an environment
misconfiguration, instead they should return a hard error (code 99).

Signed-off-by: Glenn Washburn <development@efficientek.com>
---
 INSTALL | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/INSTALL b/INSTALL
index 22b68cb6c766..4262bf3cd35c 100644
--- a/INSTALL
+++ b/INSTALL
@@ -66,7 +66,7 @@ More cross compiling toolchains can be found at the following trusted sites:
 * https://mirrors.kernel.org/pub/tools/crosstool/
 * https://toolchains.bootlin.com/
 
-Prerequisites for make-check:
+Prerequisites for running make-check successfully:
 
 * qemu, specifically the binary "qemu-system-ARCH" where ARCH is the
   architecture GRUB has been built for; the "qemu-system" package on Debian
@@ -86,6 +86,8 @@ Prerequisites for make-check:
     reiserfs, udf, xfs
   - On newer kernels, the exfat kernel modules may be used instead of the
     exfat FUSE filesystem
+  - Kernel version 6.12.x was the last series to include reiserfs support,
+    so later kernels will fail the reiser filesystem test.
 * The following are Debian named packages required mostly for the full
   suite of filesystem testing (but some are needed by other tests as well):
   - btrfs-progs, dosfstools, e2fsprogs, erofs-utils, exfatprogs, exfat-fuse,
@@ -96,8 +98,8 @@ Prerequisites for make-check:
   - attr, cpio, g++, gawk, parted, recode, tar, util-linux
 
 Note that `make check' will run and many tests may complete successfully
-with only a subset of these prerequisites. However, some tests may be
-skipped or fail due to missing prerequisites.
+with only a subset of these prerequisites. However, some tests may fail
+due to missing prerequisites.
 
 To build the documentation you'll need:
 * texinfo, for the info and html documentation
-- 
2.34.1


_______________________________________________
Grub-devel mailing list
Grub-devel@gnu.org
https://lists.gnu.org/mailman/listinfo/grub-devel

Re: [PATCH 0/5] Various doc fixes and test code explanation

[Daniel Kiper]

On Mon, Nov 17, 2025 at 06:01:39PM -0600, Glenn Washburn wrote:
> Patch #1 is a small spelling error or typo and could be folded into patch
> #2, or some other patch of trivial spelling fixes, not sure which is
> preferred. Patch #2 was created via a cursory read through. There are
> more improvments to be had and I think some parts where I was unsure of
> the meaning. The rest of the patches are self-explanatory.
>
> Glenn
>
> Glenn Washburn (5):
>   misc: Fix spelling mistakes
>   docs: Fix spelling, grammatical and usage issues with new Porting
>     section
>   docs: Add note and explanation that the privileged user is required
>     for properly running the tests
>   docs: Reorganize test section and add section on writing tests
>   INSTALL: Make note that linux kernel 6.12.x or earlier is needed

For all patches Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>...

Daniel

_______________________________________________
Grub-devel mailing list
Grub-devel@gnu.org
https://lists.gnu.org/mailman/listinfo/grub-devel