NuKVM/memtest86plus
3
0
Fork 0
mirror of https://github.com/memtest86plus/memtest86plus.git synced 2024-11-23 08:26:23 -06:00
Code Issues Packages Projects Releases Wiki Activity

Add ability to generate internal API documentation using Doxygen.

Browse Source
This commit is contained in:
Martin Whitaker 2022-02-19 16:17:40 +00:00
parent d09c5ed7b4
commit 76adad2fe6
45 changed files with 2967 additions and 232 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.gitignore vendored
View File

@ -18,3 +18,5 @@ memtest_shared.bin
# Directories
grub-iso
html
latex

14
app/badram.h
View File

@ -1,27 +1,29 @@
// SPDX-License-Identifier: GPL-2.0
#ifndef BADRAM_H
#define BADRAM_H
/*
* Support for generating patterns for the Linux kernel BadRAM extension.
/**
* \file
*
* Copyright (C) 2020 Martin Whitaker.
* Provides functions for generating patterns for the Linux kernel BadRAM extension.
*
* Copyright (C) 2020-2022 Martin Whitaker.
*/
#include <stdbool.h>
#include <stdint.h>
/*
/**
* Initialises the pattern array.
*/
void badram_init(void);
/*
/**
* Inserts a single faulty address into the pattern array. Returns
* true iff the array was changed.
*/
bool badram_insert(uintptr_t addr);
/*
/**
* Displays the pattern array in the scrollable display region in the
* format used by the Linux kernel.
*/

4
app/config.h
View File

@ -1,7 +1,9 @@
// SPDX-License-Identifier: GPL-2.0
#ifndef CONFIG_H
#define CONFIG_H
/*
/**
* \file
*
* Provides the configuration settings and pop-up menu.
*
* Copyright (C) 2020-2022 Martin Whitaker.

4
app/display.h
View File

@ -1,7 +1,9 @@
// SPDX-License-Identifier: GPL-2.0
#ifndef DISPLAY_H
#define DISPLAY_H
/*
/**
* \file
*
* Provides (macro) functions that implement the UI display.
* All knowledge about the display layout is encapsulated here.
*

18
app/error.h
View File

@ -1,10 +1,12 @@
// SPDX-License-Identifier: GPL-2.0
#ifndef ERROR_H
#define ERROR_H
/*
/**
* \file
*
* Provides functions that can be called by the memory tests to report errors.
*
* Copyright (C) 2020-2021 Martin Whitaker.
* Copyright (C) 2020-2022 Martin Whitaker.
*/
#include <stdbool.h>
@ -12,34 +14,34 @@
#include "test.h"
/*
/**
* The number of errors recorded during the current run.
*/
extern uint64_t error_count;
/*
/**
* Initialises the error records.
*/
void error_init(void);
/*
/**
* Adds an address error to the error reports.
*/
void addr_error(testword_t *addr1, testword_t *addr2, testword_t good, testword_t bad);
/*
/**
* Adds a data error to the error reports.
*/
void data_error(testword_t *addr, testword_t good, testword_t bad, bool use_for_badram);
#if REPORT_PARITY_ERRORS
/*
/**
* Adds a parity error to the error reports.
*/
void parity_error(void);
#endif
/*
/**
* Refreshes the error display after the error mode is changed.
*/
void error_update(void);

8
app/interrupt.h
View File

@ -1,15 +1,17 @@
// SPDX-License-Identifier: GPL-2.0
#ifndef INTERRUPT_H
#define INTERRUPT_H
/*
/**
* \file
*
* Provides the interrupt handler.
*
* Copyright (C) 2020 Martin Whitaker.
* Copyright (C) 2020-2022 Martin Whitaker.
*/
struct trap_regs;
/*
/**
* Handles an interrupt.
*/
void interrupt(struct trap_regs *trap_regs);

34
app/test.h
View File

@ -1,7 +1,9 @@
// SPDX-License-Identifier: GPL-2.0
#ifndef TEST_H
#define TEST_H
/*
/**
* \file
*
* Provides types and variables used when performing the memory tests.
*
* Copyright (C) 2020-2022 Martin Whitaker.
@ -16,7 +18,7 @@
#include "barrier.h"
#include "spinlock.h"
/*
/**
* A mapping from a CPU core number to the index number of the memory chunk
* it operates on when performing a memory test in parallel across all the
* enabled cores.
@ -29,22 +31,22 @@ extern uint8_t chunk_index[MAX_CPUS];
*/
extern int num_active_cpus;
/*
/**
* The current master CPU core.
*/
extern int master_cpu;
/*
/**
* A barrier used when running tests.
*/
extern barrier_t *run_barrier;
/*
/**
* A mutex used when reporting errors or printing trace information.
*/
extern spinlock_t *error_mutex;
/*
/**
* The word width (in bits) used for memory testing.
*/
#ifdef __x86_64__
@ -53,17 +55,17 @@ extern spinlock_t *error_mutex;
#define TESTWORD_WIDTH 32
#endif
/*
/**
* The number of hex digits needed to display a memory test word.
*/
#define TESTWORD_DIGITS (TESTWORD_WIDTH / 4)
/*
/**
* The word type used for memory testing.
*/
typedef uintptr_t testword_t;
/*
/**
* A virtual memory segment descriptor.
*/
typedef struct {
@ -72,35 +74,35 @@ typedef struct {
testword_t *end;
} vm_map_t;
/*
/**
* The list of memory segments currently mapped into virtual memory.
*/
extern vm_map_t vm_map[MAX_MEM_SEGMENTS];
/*
/**
* The number of memory segments currently mapped into virtual memory.
*/
extern int vm_map_size;
/*
/**
* The number of completed test passes.
*/
extern int pass_num;
/*
/**
* The current test number.
*/
extern int test_num;
/*
/**
* A flag indicating that testing should be restarted due to a configuration
* change.
*/
extern bool restart;
/*
/**
* A flag indicating that the current test should be aborted.
*/
extern bool bail;
/*
/**
* The base address of the block of memory currently being tested.
*/
extern uintptr_t test_addr[MAX_CPUS];

8
boot/boot.h
View File

@ -1,9 +1,11 @@
// SPDX-License-Identifier: GPL-2.0
#ifndef BOOT_H
#define BOOT_H
/*
* Definitions used in the boot code. Also defines exported symbols needed
* in the main code.
/**
* \file
*
* Provides definitions used in the boot code. Also defines exported symbols
* needed in the main code.
*
* Copyright (C) 2020-2022 Martin Whitaker.
*/

6
boot/bootparams.h
View File

@ -1,13 +1,15 @@
// SPDX-License-Identifier: GPL-2.0
#ifndef BOOTPARAMS_H
#define BOOTPARAMS_H
/*
/**
* \file
*
* Provides definitions for the boot params structure passed to us by
* intermediate bootloaders when using the Linux boot protocol. This matches
* the Linux boot_params struct, although we only define the fields we are
* interested in.
*
* Copyright (C) 2020-2021 Martin Whitaker.
* Copyright (C) 2020-2022 Martin Whitaker.
*/
#include <stdint.h>

16
boot/efi.h
View File

@ -1,11 +1,13 @@
// SPDX-License-Identifier: GPL-2.0
#ifndef EFI_H
#define EFI_H
/*
/**
* \file
*
* Provides definitions for accessing the UEFI boot services and configuration
* tables.
*
* Copyright (C) 2020 Martin Whitaker.
* Copyright (C) 2020-2022 Martin Whitaker.
*/
#include <stdint.h>
@ -16,7 +18,7 @@
#define NATIVE_MSB 0x80000000
#endif
/*
/**
* EFI_STATUS values.
*/
#define EFI_SUCCESS 0
@ -27,17 +29,17 @@
#define EFI_NOT_FOUND (NATIVE_MSB | 14)
#define EFI_ABORTED (NATIVE_MSB | 21)
/*
/**
* EFI_LOCATE_SEARCH_TYPE values.
*/
#define EFI_LOCATE_BY_PROTOCOL 2
/*
/**
* EFI_ALLOCATE_TYPE values.
*/
#define EFI_ALLOCATE_ADDRESS 2
/*
/**
* EFI_MEMORY_TYPE values.
*/
#define EFI_LOADER_CODE 1
@ -47,7 +49,7 @@
#define EFI_CONVENTIONAL_MEMORY 7
#define EFI_ACPI_RECLAIM_MEMORY 9
/*
/**
* EFI_GRAPHICS_PIXEL_FORMAT values.
*/
#define PIXEL_RGB_RESERVED_8BIT_PER_COLOR 0

2574
doc/Doxyfile Normal file
View File

File diff suppressed because it is too large Load Diff

76
doc/README_DEVEL.md Normal file
View File

@ -0,0 +1,76 @@
# Developer's Guide
This is the developer's guide to the PCMemTest source code. The user's guide
can be found in the README.md file in the top level directory.
## Code Organisation
The source code is divided into the following categories, each contained in a
subdirectory of the same name:
* app
The main application and framework for running the memory tests.
* boot
The code that transitions from the BIOS or bootloader entry point to the
start of the main application.
* lib
The subset of the C standard library that is used by PCMemTest plus other
hardware-independent low-level support functions.
* system
Low-level support functions that interface to the hardware.
* tests
The individual memory tests.
The boot code is mostly written in AT&T syntax x86 assembly language. The
remaining code is written in C.
Each category is further subdivided into multiple source files, splitting the
code into small units of closely related functionality. For the C code, the
API for each unit is defined in a header (`.h`) file and the implementation
(if required) is found in the correspondingly named source (`.c`) file.
## Code Documentation
Doxygen can be used to automatically generate HTML documentation for the API
for each code unit from the comments in the C header files. To regenerate the
documentation, change directory into the `doc` subdirectory and run `doxygen`.
## Coding Conventions
### C Code
Macro names and enumeration values are written in upper case separated by
underscores. All other identifiers are written in lower case separated by
underscores. Both excessive length and excessive abbreviation are avoided.
Line length is normally limited to 120 characters.
Indentation is 4 spaces. No hard tab characters are used.
Opening braces for function bodies are put on a new line. Other opening braces
are put on the same line as the construct that introduces them.
The C11 dialect is used. In particular, variable declarations and statements
are interspersed and loop variables are declared within the `for` loop
construct.
### Assembly Code
Labels are written in lower case separated by underscores. Op-codes and
register names are written in lower case.
Line length is normally limited to 120 characters.
Indentation is 8 spaces using hard tab characters.
The C preprocessor is used for defining constant values and expressions.
Macro names are written in upper case separated by underscores.

12
lib/barrier.h
View File

@ -1,15 +1,17 @@
// SPDX-License-Identifier: GPL-2.0
#ifndef BARRIER_H
#define BARRIER_H
/*
/**
* \file
*
* Provides a barrier synchronisation primitive.
*
* Copyright (C) 2020 Martin Whitaker.
* Copyright (C) 2020-2022 Martin Whitaker.
*/
#include "spinlock.h"
/*
/**
* A barrier object.
*/
typedef struct
@ -21,12 +23,12 @@ typedef struct
spinlock_t st2;
} barrier_t;
/*
/**
* Initialises the barrier to block the specified number of threads.
*/
void barrier_init(barrier_t *barrier, int num_threads);
/*
/**
* Waits for all threads to arrive at the barrier.
*/
void barrier_wait(barrier_t *barrier);

12
lib/ctype.h
View File

@ -1,25 +1,27 @@
// SPDX-License-Identifier: GPL-2.0
#ifndef CTYPE_H
#define CTYPE_H
/*
/**
* \file
*
* Provides a subset of the functions normally provided by <ctype.h>.
*
* Copyright (C) 2020 Martin Whitaker.
* Copyright (C) 2020-2022 Martin Whitaker.
*/
/*
/**
* If c is a lower-case letter, returns its upper-case equivalent, otherwise
* returns c. Assumes c is an ASCII character.
*/
int toupper(int c);
/*
/**
* Returns 1 if c is a decimal digit, otherwise returns 0. Assumes c is an
* ASCII character.
*/
int isdigit(int c);
/*
/**
* Returns 1 if c is a hexadecimal digit, otherwise returns 0. Assumes c is an
* ASCII character.
*/

22
lib/print.h
View File

@ -1,28 +1,30 @@
// SPDX-License-Identifier: GPL-2.0
#ifndef PRINT_H
#define PRINT_H
/*
/**
* \file
*
* Provides functions to print strings and formatted values to the screen.
*
* Copyright (C) 2020 Martin Whitaker.
* Copyright (C) 2020-2022 Martin Whitaker.
*/
#include <stdarg.h>
#include <stdbool.h>
#include <stdint.h>
/*
/**
* Prints a single character on screen at location (row,col) and returns col+1.
*/
int printc(int row, int col, char c);
/*
/**
* Prints a string on screen starting at location (row,col) and returns the
* next column after the string.
*/
int prints(int row, int col, const char *str);
/*
/**
* Prints a signed decimal number on screen starting at location (row,col) in
* a field of at least length characters, optionally padding the number with
* leading zeros, and optionally left-justifying instead of right-justifying
@ -30,7 +32,7 @@ int prints(int row, int col, const char *str);
*/
int printi(int row, int col, int value, int length, bool pad, bool left);
/*
/**
* Prints an unsigned decimal number on screen starting at location (row,col)
* in a field of at least length characters, optionally padding the number with
* leading zeros, and optionally left-justifying instead of right-justifying in
@ -38,7 +40,7 @@ int printi(int row, int col, int value, int length, bool pad, bool left);
*/
int printu(int row, int col, uintptr_t value, int length, bool pad, bool left);
/*
/**
* Prints an unsigned hexadecimal number on screen starting at location (row,col)
* in a field of at least length characters, optionally padding the number with
* leading zeros, and optionally left-justifying instead of right-justifying in
@ -46,7 +48,7 @@ int printu(int row, int col, uintptr_t value, int length, bool pad, bool left);
*/
int printx(int row, int col, uintptr_t value, int length, bool pad, bool left);
/*
/**
* Prints a K<unit> value on screen starting at location (row,col) in a field of
* at least length characters, optionally padding the number with leading zeros,
* and optionally left-justifying instead of right-justifying in the field. The
@ -55,7 +57,7 @@ int printx(int row, int col, uintptr_t value, int length, bool pad, bool left);
*/
int printk(int row, int col, uintptr_t value, int length, bool pad, bool left);
/*
/**
* Emulates the standard printf function. Printing starts at location (row,col).
*
* The conversion flags supported are:
@ -77,7 +79,7 @@ int printk(int row, int col, uintptr_t value, int length, bool pad, bool left);
*/
int printf(int row, int col, const char *fmt, ...);
/*
/**
* The alternate form of printf.
*/
int vprintf(int row, int col, const char *fmt, va_list args);

8
lib/read.h
View File

@ -1,15 +1,17 @@
// SPDX-License-Identifier: GPL-2.0
#ifndef READ_H
#define READ_H
/*
/**
* \file
*
* Provides a function to read a numeric value.
*
* Copyright (C) 2020 Martin Whitaker.
* Copyright (C) 2020-2022 Martin Whitaker.
*/
#include <stdint.h>
/*
/**
* Returns an unsigned numeric value entered on the keyboard. Echoes the
* input to the display field located at (row,col), limiting it to field_width
* characters. If the entered value is prefixed by "0x", assumes base 16,

14
lib/spinlock.h
View File

@ -1,20 +1,22 @@
// SPDX-License-Identifier: GPL-2.0
#ifndef SPINLOCK_H
#define SPINLOCK_H
/*
/**
* \file
*
* Provides a lightweight mutex synchronisation primitive.
*
* Copyright (C) 2020 Martin Whitaker.
* Copyright (C) 2020-2022 Martin Whitaker.
*/
#include <stdbool.h>
/*
/**
* A mutex object. Use spin_unlock() to initialise prior to first use.
*/
typedef volatile bool spinlock_t;
/*
/**
* Spins until the mutex is unlocked.
*/
static inline void spin_wait(spinlock_t *lock)
@ -26,7 +28,7 @@ static inline void spin_wait(spinlock_t *lock)
}
}
/*
/**
* Spins until the mutex is unlocked, then locks the mutex.
*/
static inline void spin_lock(spinlock_t *lock)
@ -41,7 +43,7 @@ static inline void spin_lock(spinlock_t *lock)
}
}
/*
/**
* Unlocks the mutex.
*/
static inline void spin_unlock(spinlock_t *lock)

20
lib/string.h
View File

@ -1,15 +1,17 @@
// SPDX-License-Identifier: GPL-2.0
#ifndef STRING_H
#define STRING_H
/*
/**
* \file
*
* Provides a subset of the functions normally provided by <string.h>.
*
* Copyright (C) 2020 Martin Whitaker.
* Copyright (C) 2020-2022 Martin Whitaker.
*/
#include <stddef.h>
/*
/**
* Compares the first n bytes of the memory areas pointed to by s1 and s2
* and returns 0 if all bytes are the same or the numerical difference
* between the first mismatching byte in s1 (interpreted as an unsigned
@ -17,32 +19,32 @@
*/
int memcmp(const void *s1, const void *s2, size_t n);
/*
/**
* Copies n bytes from the memory area pointed to by src to the memory area
* pointed to by dest and returns a pointer to dest. The memory areas must
* not overlap.
*/
void *memcpy(void *dst, const void *src, size_t n);
/*
/**
* Copies n bytes from the memory area pointed to by src to the memory area
* pointed to by dest and returns a pointer to dest. The memory areas may
* overlap.
*/
void *memmove(void *dest, const void *src, size_t n);
/*
/**
* Fills the first n bytes of the memory area pointed to by s with the byte
* value c.
*/
void *memset(void *s, int c, size_t n);
/*
/**
* Returns the string length, excluding the terminating null character.
*/
size_t strlen(const char *s);
/*
/**
* Compares at most the first n characters in the strings s1 and s2 and
* returns 0 if all characters are the same or the numerical difference
* between the first mismatching character in s1 (interpreted as a signed
@ -50,7 +52,7 @@ size_t strlen(const char *s);
*/
int strncmp(const char *s1, const char *s2, size_t n);
/*
/**
* Finds the first occurrence of the substring needle in the string haystack
* and returns a pointer to the beginning of the located substring, or NULL
* if the substring is not found.

10
lib/unistd.h
View File

@ -1,18 +1,20 @@
// SPDX-License-Identifier: GPL-2.0
#ifndef UNISTD_H
#define UNISTD_H
/*
/**
* \file
*
* Provides a subset of the functions normally provided by <unistd.h>.
*
* Copyright (C) 2020 Martin Whitaker.
* Copyright (C) 2020-2022 Martin Whitaker.
*/
/*
/**
* Sleeps for at least usec microseconds.
*/
void usleep(unsigned int usec);
/*
/**
* Sleeps for at least sec seconds.
*/
void sleep(unsigned int sec);

12
system/cache.h
View File

@ -1,13 +1,15 @@
// SPDX-License-Identifier: GPL-2.0
#ifndef CACHE_H
#define CACHE_H
/*
/**
* \file
*
* Provides functions to enable, disable, and flush the CPU caches.
*
* Copyright (C) 2020-2021 Martin Whitaker.
* Copyright (C) 2020-2022 Martin Whitaker.
*/
/*
/**
* Disable the CPU caches.
*/
static inline void cache_off(void)
@ -35,7 +37,7 @@ static inline void cache_off(void)
#endif
}
/*
/**
* Enable the CPU caches.
*/
static inline void cache_on(void)
@ -61,7 +63,7 @@ static inline void cache_on(void)
#endif
}
/*
/**
* Flush the CPU caches.
*/
static inline void cache_flush(void)

12
system/cpuid.h
View File

@ -1,7 +1,9 @@
// SPDX-License-Identifier: GPL-2.0
#ifndef CPUID_H
#define CPUID_H
/*
/**
* \file
*
* Provides access to the CPUID information.
*
* Copyright (C) 2020-2022 Martin Whitaker.
@ -12,7 +14,7 @@
#include <stdint.h>
/*
/**
* Structures that hold the collected CPUID information.
*/
@ -172,17 +174,17 @@ typedef union {
};
} cpuid4_ecx_t;
/*
/**
* The CPUID information collected by cpuid_init();
*/
extern cpuid_info_t cpuid_info;
/*
/**
* Reads the CPUID information and stores it in cpuid_info.
*/
void cpuid_init(void);
/*
/**
* Executes the cpuid instruction.
*/
static inline void cpuid(uint32_t op, uint32_t count, uint32_t *eax, uint32_t *ebx, uint32_t *ecx, uint32_t *edx)

22
system/cpuinfo.h
View File

@ -1,51 +1,53 @@
// SPDX-License-Identifier: GPL-2.0
#ifndef CPUINFO_H
#define CPUINFO_H
/*
/**
* \file
*
* Provides information about the CPU type, clock speed and cache sizes.
*
* Copyright (C) 2020 Martin Whitaker.
* Copyright (C) 2020-2022 Martin Whitaker.
*/
#include <stdbool.h>
#include <stdint.h>
/*
/**
* A string identifying the CPU make and model.
*/
extern const char *cpu_model;
/*
/**
* A number identifying the integrated memory controller type.
*/
extern uint32_t imc_type;
/*
/**
* The size of the L1 cache in KB.
*/
extern int l1_cache;
/*
/**
* The size of the L2 cache in KB.
*/
extern int l2_cache;
/*
/**
* The size of the L3 cache in KB.
*/
extern int l3_cache;
/*
/**
* A flag indicating that we can't read the core temperature on this CPU.
*/
extern bool no_temperature;
/*
/**
* The TSC clock speed in kHz. Assumed to be the nominal CPU clock speed.
*/
extern uint32_t clks_per_msec;
/*
/**
* Determines the CPU info and stores it in the exported variables.
*/
void cpuinfo_init(void);

6
system/ehci.h
View File

@ -1,7 +1,9 @@
// SPDX-License-Identifier: GPL-2.0
#ifndef EHCI_H
#define EHCI_H
/*
/**
* \file
*
* Provides support for USB keyboards connected via an EHCI controller.
*
* Copyright (C) 2021-2022 Martin Whitaker.
@ -11,7 +13,7 @@
#include "usbhcd.h"
/*
/**
* Initialises the EHCI device identified by bus, dev, func, and base_addr,
* scans all the attached USB devices, and configures any HID USB keyboard
* devices it finds to generate periodic interrupt transfers that report key

10
system/font.h
View File

@ -1,22 +1,24 @@
// SPDX-License-Identifier: GPL-2.0
#ifndef FONT_H
#define FONT_H
/*
/**
* \file
*
* Provides the font used for framebuffer display.
*
* Copyright (C) 2020 Martin Whitaker.
* Copyright (C) 2020-2022 Martin Whitaker.
*/
#include <stdint.h>
/*
/**
* Font size definitions.
*/
#define FONT_WIDTH 8
#define FONT_HEIGHT 16
#define FONT_CHARS 256
/*
/**
* The font data.
*/
extern const uint8_t font_data[FONT_CHARS][FONT_HEIGHT];

12
system/hwctrl.h
View File

@ -1,23 +1,25 @@
// SPDX-License-Identifier: GPL-2.0
#ifndef HWCTRL_H
#define HWCTRL_H
/*
/**
* \file
*
* Provides miscellaneous hardware control functions.
*
* Copyright (C) 2020 Martin Whitaker.
* Copyright (C) 2020-2022 Martin Whitaker.
*/
/*
/**
* Reboots the machine.
*/
void reboot(void);
/*
/**
* Turns off the floppy motor.
*/
void floppy_off();
/*
/**
* Disables the screen cursor.
*/
void cursor_off();

6
system/io.h
View File

@ -1,7 +1,9 @@
// SPDX-License-Identifier: GPL-2.0
#ifndef IO_H
#define IO_H
/*
/**
* \file
*
* Provides macro definitions for the x86 IO instructions
* inb/inw/inl/outb/outw/outl and the "string versions" of the same
* (insb/insw/insl/outsb/outsw/outsl). You can also use "pausing"
@ -78,7 +80,7 @@ __OUTS(b)
__OUTS(w)
__OUTS(l)
/*
/**
* Note that due to the way __builtin_constant_p() works, you
* - can't use it inside a inline function (it will never be true)
* - you don't have to worry about side effects within the __builtin..

21
system/keyboard.h
View File

@ -1,22 +1,23 @@
// SPDX-License-Identifier: GPL-2.0
#ifndef KEYBOARD_H
#define KEYBOARD_H
#include <stdbool.h>
/*
/**
* \file
*
* Provides the keyboard interface. It converts incoming key codes to
* ASCII characters.
*
* Copyright (C) 2020-2021 Martin Whitaker.
* Copyright (C) 2020-2022 Martin Whitaker.
*/
/*
#include <stdbool.h>
/**
* The Escape character.
*/
#define ESC 27
/*
/**
* A set of supported keyboard types.
*/
typedef enum {
@ -25,17 +26,17 @@ typedef enum {
KT_USB = 2
} keyboard_types_t;
/*
/**
* The set of enabled keyboard types
*/
extern keyboard_types_t keyboard_types;
/*
/**
* Initialises the keyboard interface.
*/
void keyboard_init(bool pause_at_end);
/*
/**
* Checks if a key has been pressed and returns the primary ASCII character
* corresponding to that key if so, otherwise returns the null character.
* F1 to F10 are mapped to the corresponding decimal digit (F10 -> 0). All

12
system/memrw32.h
View File

@ -1,17 +1,19 @@
// SPDX-License-Identifier: GPL-2.0
#ifndef MEMRW32_H
#define MEMRW32_H
/*
/**
* \file
*
* Provides some 32-bit memory access functions. These stop the compiler
* optimizing accesses which need to be ordered and atomic. Mostly used
* for accessing memory-mapped hardware registers.
*
* Copyright (C) 2021 Martin Whitaker.
* Copyright (C) 2021-2022 Martin Whitaker.
*/
#include <stdint.h>
/*
/**
* Reads and returns the value stored in the 32-bit memory location pointed
* to by ptr.
*/
@ -27,7 +29,7 @@ static inline uint32_t read32(const volatile uint32_t *ptr)
return val;
}
/*
/**
* Writes val to the 32-bit memory location pointed to by ptr.
*/
static inline void write32(const volatile uint32_t *ptr, uint32_t val)
@ -41,7 +43,7 @@ static inline void write32(const volatile uint32_t *ptr, uint32_t val)
);
}
/*
/**
* Writes val to the 32-bit memory location pointed to by ptr. Reads it
* back (and discards it) to ensure the write is complete.
*/

12
system/memrw64.h
View File

@ -1,17 +1,19 @@
// SPDX-License-Identifier: GPL-2.0
#ifndef MEMRW64_H
#define MEMRW64_H
/*
/**
* \file
*
* Provides some 64-bit memory access functions. These stop the compiler
* optimizing accesses which need to be ordered and atomic. Mostly used
* for accessing memory-mapped hardware registers.
*
* Copyright (C) 2021 Martin Whitaker.
* Copyright (C) 2021-2022 Martin Whitaker.
*/
#include <stdint.h>
/*
/**
* Reads and returns the value stored in the 64-bit memory location pointed
* to by ptr.
*/
@ -27,7 +29,7 @@ static inline uint64_t read64(const volatile uint64_t *ptr)
return val;
}
/*
/**
* Writes val to the 64-bit memory location pointed to by ptr.
*/
static inline void write64(const volatile uint64_t *ptr, uint64_t val)
@ -41,7 +43,7 @@ static inline void write64(const volatile uint64_t *ptr, uint64_t val)
);
}
/*
/**
* Writes val to the 64-bit memory location pointed to by ptr. Reads it
* back (and discards it) to ensure the write is complete.
*/

6
system/memsize.h
View File

@ -1,10 +1,12 @@
// SPDX-License-Identifier: GPL-2.0
#ifndef MEMSIZE_H
#define MEMSIZE_H
/*
/**
* \file
*
* Provides some convenient constants and constant constructors.
*
* Copyright (C) 2020 Martin Whitaker.
* Copyright (C) 2020-2022 Martin Whitaker.
*/
#include <stddef.h>

4
system/msr.h
View File

@ -1,7 +1,9 @@
// SPDX-License-Identifier: GPL-2.0
#ifndef MSR_H
#define MSR_H
/*
/**
* \file
*
* Provides access to the CPU machine-specific registers.
*
* Copyright (C) 2020-2022 Martin Whitaker.

6
system/ohci.h
View File

@ -1,7 +1,9 @@
// SPDX-License-Identifier: GPL-2.0
#ifndef OHCI_H
#define OHCI_H
/*
/**
* \file
*
* Provides support for USB keyboards connected via an OHCI controller.
*
* Copyright (C) 2021-2022 Martin Whitaker.
@ -11,7 +13,7 @@
#include "usbhcd.h"
/*
/**
* Initialises the OHCI device found at base_addr, scans all the attached USB
* devices, and configures any HID USB keyboard devices it finds to generate
* periodic interrupt transfers that report key presses. Initialises hcd and

20
system/pci.h
View File

@ -1,10 +1,12 @@
// SPDX-License-Identifier: GPL-2.0
#ifndef PCI_H
#define PCI_H
/*
/**
* \file
*
* Provides functions to perform PCI configuration space reads and writes.
*
* Copyright (C) 2020-2021 Martin Whitaker.
* Copyright (C) 2020-2022 Martin Whitaker.
*/
#include <stdint.h>
@ -13,44 +15,44 @@
#define PCI_MAX_DEV 32
#define PCI_MAX_FUNC 8
/*
/**
* Initialises the PCI access support.
*/
void pci_init(void);
/*
/**
* Returns an 8 bit value read from the specified bus+device+function+register
* address in the PCI configuration address space.
*/
uint8_t pci_config_read8(int bus, int dev, int func, int reg);
/*
/**
* Returns a 16 bit value read from the specified bus+device+function+register
* address in the PCI configuration address space. The address must be 16-bit
* aligned.
*/
uint16_t pci_config_read16(int bus, int dev, int func, int reg);
/*
/**
* Returns a 32 bit value read from the specified bus+device+function+register
* address in the PCI configuration address space. The address must be 32-bit
* aligned.
*/
uint32_t pci_config_read32(int bus, int dev, int func, int reg);
/*
/**
* Writes an 8 bit value to the specified bus+device+function+register address
* in the PCI configuration address space.
*/
void pci_config_write8(int bus, int dev, int func, int reg, uint8_t value);
/*
/**
* Writes a 16 bit value to the specified bus+device+function+register address
* in the PCI configuration address space. The address must be 16-bit aligned.
*/
void pci_config_write16(int bus, int dev, int func, int reg, uint16_t value);
/*
/**
* Writes a 32 bit value to the specified bus+device+function+register address
* in the PCI configuration address space. The address must be 32-bit aligned.
*/

6
system/pmem.h
View File

@ -1,10 +1,12 @@
// SPDX-License-Identifier: GPL-2.0
#ifndef PMEM_H
#define PMEM_H
/*
/**
* \file
*
* Provides a description of the system physical memory map.
*
* Copyright (C) 2020 Martin Whitaker.
* Copyright (C) 2020-2022 Martin Whitaker.
*/
#include <stddef.h>

30
system/screen.h
View File

@ -1,22 +1,24 @@
// SPDX-License-Identifier: GPL-2.0
#ifndef SCREEN_H
#define SCREEN_H
/*
/**
* \file
*
* Provides the display interface. It provides an 80x25 VGA-compatible text
* display.
*
* Copyright (C) 2020 Martin Whitaker.
* Copyright (C) 2020-2022 Martin Whitaker.
*/
#include <stdint.h>
/*
/**
* Screen size definitions. The screen size cannot be changed.
*/
#define SCREEN_WIDTH 80
#define SCREEN_HEIGHT 25
/*
/**
* Colours that can be used for the foreground or background.
*/
typedef enum {
@ -30,58 +32,58 @@ typedef enum {
WHITE = 7
} screen_colour_t;
/*
/**
* Modifier that can be added to any foreground colour.
* Has no effect on background colours.
*/
#define BOLD 8
/*
/**
* Initialise the display interface.
*/
void screen_init(void);
/*
/**
* Set the foreground colour used for subsequent drawing operations.
*/
void set_foreground_colour(screen_colour_t colour);
/*
/**
* Set the background colour used for subsequent drawing operations.
*/
void set_background_colour(screen_colour_t colour);
/*
/**
* Clear the whole screen, using the current background colour.
*/
void clear_screen(void);
/*
/**
* Clear the specified region of the screen, using the current background
* colour.
*/
void clear_screen_region(int start_row, int start_col, int end_row, int end_col);
/*
/**
* Move the contents of the specified region of the screen up one row,
* discarding the top row, and clearing the bottom row, using the current
* background colour.
*/
void scroll_screen_region(int start_row, int start_col, int end_row, int end_col);
/*
/**
* Copy the contents of the specified region of the screen into the supplied
* buffer.
*/
void save_screen_region(int start_row, int start_col, int end_row, int end_col, uint16_t buffer[]);
/*
/**
* Restore the specified region of the screen from the supplied buffer.
* This restores both text and colours.
*/
void restore_screen_region(int start_row, int start_col, int end_row, int end_col, const uint16_t buffer[]);
/*
/**
* Write the supplied character to the specified screen location, using the
* current foreground colour. Has no effect if the location is outside the
* screen.

26
system/smp.h
View File

@ -1,7 +1,9 @@
// SPDX-License-Identifier: GPL-2.0
#ifndef _SMP_H_
#define _SMP_H_
/*
/**
* \file
*
* Provides support for multi-threaded operation.
*
* Copyright (C) 2020-2022 Martin Whitaker.
@ -15,12 +17,12 @@
#include "barrier.h"
#include "spinlock.h"
/*
/**
* The maximum number of CPU cores that can be used.
*/
#define MAX_CPUS (1 + MAX_APS)
/*
/**
* The current state of a CPU core.
*/
typedef enum __attribute__ ((packed)) {
@ -30,49 +32,49 @@ typedef enum __attribute__ ((packed)) {
CPU_STATE_HALTED = 3
} cpu_state_t;
/*
/**
* The number of available CPU cores. Initially this is 1, but may increase
* after calling smp_init().
*/
extern int num_available_cpus;
/*
/**
* The search step that located the ACPI RSDP (for debug).
*/
extern const char *rsdp_source;
/*
/**
* The address of the ACPI RSDP (for debug).
*/
extern uintptr_t rsdp_addr;
/*
/**
* Initialises the SMP state and detects the number of available CPU cores.
*/
void smp_init(bool smp_enable);
/*
/**
* Starts the APs listed as enabled in cpu_state. Returns 0 on success
* or the index number of the lowest-numbered AP that failed to start.
*/
int smp_start(cpu_state_t cpu_state[MAX_CPUS]);
/*
/**
* Sends a non-maskable interrupt to the CPU core whose ordinal number
* is cpu_num.
*/
bool smp_send_nmi(int cpu_num);
/*
/**
* Returns the ordinal number of the calling CPU core.
*/
int smp_my_cpu_num(void);
/*
/**
* Allocates and initialises a barrier object in pinned memory.
*/
barrier_t *smp_alloc_barrier(int num_threads);
/*
/**
* Allocates and initialises a spinlock object in pinned memory.
*/
spinlock_t *smp_alloc_mutex();

8
system/temperature.h
View File

@ -1,13 +1,15 @@
// SPDX-License-Identifier: GPL-2.0
#ifndef TEMPERATURE_H
#define TEMPERATURE_H
/*
/**
* \file
*
* Provides a function to read the CPU core temperature.
*
* Copyright (C) 2020 Martin Whitaker.
* Copyright (C) 2020-2022 Martin Whitaker.
*/
/*
/**
* Returns the current temperature of the CPU. Returns 0 if
* the temperature cannot be read.
*/

8
system/tsc.h
View File

@ -1,10 +1,12 @@
// SPDX-License-Identifier: GPL-2.0
#ifndef TSC_H
#define TSC_H
/*
/**
* \file
*
* Provides access to the CPU timestamp counter.
*
* Copyright (C) 2020 Martin Whitaker.
* Copyright (C) 2020-2022 Martin Whitaker.
*/
#include <stdint.h>
@ -22,7 +24,7 @@
: "edx" \
)
/*
/**
* Reads and returns the timestamp counter value.
*/
static inline uint64_t get_tsc(void)

4
system/usb.h
View File

@ -1,7 +1,9 @@
// SPDX-License-Identifier: GPL-2.0
#ifndef USB_H
#define USB_H
/*
/**
* \file
*
* Provides definitions of various values and data structures defined by the
* USB specifications.
*

50
system/usbhcd.h
View File

@ -1,7 +1,9 @@
// SPDX-License-Identifier: GPL-2.0
#ifndef USBHCD_H
#define USBHCD_H
/*
/**
* \file
*
* Provides the base USB host controller driver for USB keyboard support.
*
* This is an object-oriented design. The hcd_methods_t structure defines
@ -25,13 +27,13 @@
#include "usb.h"
/*
/**
* The size of the data transfer buffer in a host controller driver workspace.
* This aligns the start of the driver private data to a 1024 byte boundary.
*/
#define HCD_DATA_BUFFER_SIZE (1024 - sizeof(size_t))
/*
/**
* A USB device speed (used internally by the various HCI drivers).
*/
typedef enum __attribute__ ((packed)) {
@ -41,7 +43,7 @@ typedef enum __attribute__ ((packed)) {
USB_SPEED_HIGH = 3
} usb_speed_t;
/*
/**
* A USB endpoint descriptor (used internally by the various HCI drivers).
*/
typedef struct __attribute__ ((packed)) {
@ -55,7 +57,7 @@ typedef struct __attribute__ ((packed)) {
uint8_t reserved;
} usb_ep_t;
/*
/**
* A USB hub descriptor (used internally by the various HCI drivers).
*/
typedef struct __attribute__ ((packed)) {
@ -67,12 +69,12 @@ typedef struct __attribute__ ((packed)) {
uint8_t power_up_delay;
} usb_hub_t;
/*
/**
* A USB host controller driver object reference.
*/
typedef const struct usb_hcd_s *usb_hcd_r;
/*
/**
* A USB host controller driver method table.
*/
typedef struct {
@ -87,7 +89,7 @@ typedef struct {
uint8_t (*get_keycode) (usb_hcd_r);
} hcd_methods_t;
/*
/**
* A USB host controller driver workspace. This is extended by each HCI driver
* to append its private data.
*/
@ -96,7 +98,7 @@ typedef struct __attribute__((packed)) {
size_t data_length;
} hcd_workspace_t;
/*
/**
* A USB host controller driver object.
*/
typedef struct usb_hcd_s {
@ -104,7 +106,7 @@ typedef struct usb_hcd_s {
hcd_workspace_t *ws;
} usb_hcd_t;
/*
/**
* A set of USB device initialisation options.
*/
typedef enum {
@ -112,14 +114,14 @@ typedef enum {
USB_EXTRA_RESET = 1
} usb_init_options_t;
/*
/**
* The selected USB device initialisation options.
*
* Used internally by the various HCI drivers.
*/
extern usb_init_options_t usb_init_options;
/*
/**
* Constructs a USB setup packet in buffer using the provided values.
*
* Used internally by the various HCI drivers.
@ -152,7 +154,7 @@ static inline int default_max_packet_size(usb_speed_t device_speed)
}
}
/*
/**
* Returns true if size is a valid value for the maximum packet size for a
* USB device running at the given speed.
*
@ -163,7 +165,7 @@ static inline bool valid_usb_max_packet_size(int size, usb_speed_t speed)
return (size == 8) || ((speed != USB_SPEED_LOW) && (size == 16 || size == 32 || size == 64));
}
/*
/**
* Returns true if buffer appears to contain a valid USB device descriptor.
*
* Used internally by the various HCI drivers.
@ -175,7 +177,7 @@ static inline bool valid_usb_device_descriptor(const uint8_t *buffer)
return desc->length == sizeof(usb_device_desc_t) && desc->type == USB_DESC_DEVICE;
}
/*
/**
* Returns true if buffer appears to contain a valid USB configuration
* descriptor.
*
@ -188,7 +190,7 @@ static inline bool valid_usb_config_descriptor(const uint8_t *buffer)
return desc->length == sizeof(usb_config_desc_t) && desc->type == USB_DESC_CONFIGURATION;
}
/*
/**
* Returns the USB route to the device attached to the hub port specified by
* hub and port_num. The top 8 bits of the returned value contain the root
* port number and the bottom 20 bits contain the USB3 route string.
@ -197,7 +199,7 @@ static inline bool valid_usb_config_descriptor(const uint8_t *buffer)
*/
uint32_t usb_route(const usb_hub_t *hub, int port_num);
/*
/**
* Waits for all the bits set in bit_mask to be cleared in the register pointed
* to by reg or for max_time microseconds to elapse.
*
@ -205,7 +207,7 @@ uint32_t usb_route(const usb_hub_t *hub, int port_num);
*/
bool wait_until_clr(const volatile uint32_t *reg, uint32_t bit_mask, int max_time);
/*
/**
* Waits for all the bits set in bit_mask to also be set in the register pointed
* to by reg or for max_time microseconds to elapse.
*
@ -213,7 +215,7 @@ bool wait_until_clr(const volatile uint32_t *reg, uint32_t bit_mask, int max_tim
*/
bool wait_until_set(const volatile uint32_t *reg, uint32_t bit_mask, int max_time);
/*
/**
* Displays an informational message, scrolling the screen if necessary.
* Takes the same arguments as the printf function.
*
@ -221,14 +223,14 @@ bool wait_until_set(const volatile uint32_t *reg, uint32_t bit_mask, int max_tim
*/
void print_usb_info(const char *fmt, ...);
/*
/**
* Resets the specified USB hub port.
*
* Used internally by the various HCI drivers.
*/
bool reset_usb_hub_port(const usb_hcd_t *hcd, const usb_hub_t *hub, int port_num);
/*
/**
* Sets the device address for the device attached to the specified hub port
* (thus moving the device to Address state), fills in the descriptor for the
* device's default control endpoint (ep0), and leaves the device descriptor
@ -240,7 +242,7 @@ bool reset_usb_hub_port(const usb_hcd_t *hcd, const usb_hub_t *hub, int port_num
bool assign_usb_address(const usb_hcd_t *hcd, const usb_hub_t *hub, int port_num,
usb_speed_t device_speed, int device_id, usb_ep_t *ep0);
/*
/**
* Scans the specified USB device to detect whether it has any HID keyboards
* attached to it (directly or indirectly). If so, the keyboard device(s)
* are initialised and configured, as are any intermediate USB hubs, and the
@ -254,7 +256,7 @@ bool find_attached_usb_keyboards(const usb_hcd_t *hcd, const usb_hub_t *hub, int
usb_speed_t device_speed, int device_id, int *num_devices,
usb_ep_t keyboards[], int max_keyboards, int *num_keyboards);
/*
/**
* Scans the attached USB devices and initialises all HID keyboard devices
* it finds (subject to implementation limits on the number of devices).
* Records the information needed to subsequently poll those devices for
@ -264,7 +266,7 @@ bool find_attached_usb_keyboards(const usb_hcd_t *hcd, const usb_hub_t *hub, int
*/
void find_usb_keyboards(bool pause_at_end);
/*
/**
* Polls the keyboards discovered by find_usb_keyboards. Consumes and returns
* the HID key code for the first key press it detects. Returns zero if no key
* has been pressed.

6
system/vmem.h
View File

@ -1,11 +1,13 @@
// SPDX-License-Identifier: GPL-2.0
#ifndef VMEM_H
#define VMEM_H
/*
/**
* \file
*
* Provides functions to handle physical memory page mapping into virtual
* memory.
*
* Copyright (C) 2020-2021 Martin Whitaker.
* Copyright (C) 2020-2022 Martin Whitaker.
*/
#include <stdbool.h>

6
system/xhci.h
View File

@ -1,7 +1,9 @@
// SPDX-License-Identifier: GPL-2.0
#ifndef XHCI_H
#define XHCI_H
/*
/**
* \file
*
* Provides support for USB keyboards connected via an XHCI controller.
*
* Copyright (C) 2021-2022 Martin Whitaker.
@ -11,7 +13,7 @@
#include "usbhcd.h"
/*
/**
* Initialises the XHCI device found at base_addr, scans all the attached USB
* devices, and configures any HID USB keyboard devices it finds to generate
* periodic interrupt transfers that report key presses. Initialises hcd and

4
tests/test_funcs.h
View File

@ -1,7 +1,9 @@
// SPDX-License-Identifier: GPL-2.0
#ifndef TEST_FUNCS_H
#define TEST_FUNCS_H
/*
/**
* \file
*
* Provides the prototypes for the basic test functions used to implement
* the tests.
*

24
tests/test_helper.h
View File

@ -1,7 +1,9 @@
// SPDX-License-Identifier: GPL-2.0
#ifndef TEST_HELPER_H
#define TEST_HELPER_H
/*
/**
* \file
*
* Provides some common definitions and helper functions for the memory
* tests.
*
@ -13,7 +15,7 @@
#include "test.h"
/*
/**
* Test word atomic read and write functions.
*/
#ifdef __x86_64__
@ -26,24 +28,24 @@
#define write_word write32
#endif
/*
/**
* A wrapper for guiding branch prediction.
*/
#define unlikely(x) __builtin_expect(!!(x), 0)
/*
/**
* The block size processed between each update of the progress bars and
* spinners. This also affects how quickly the program will respond to the
* keyboard.
*/
#define SPIN_SIZE (1 << 27) // in testwords
/*
/**
* A macro to perform test bailout when requested.
*/
#define BAILOUT if (bail) return ticks
/*
/**
* Returns value rounded down to the nearest multiple of align_size.
*/
static inline uintptr_t round_down(uintptr_t value, size_t align_size)
@ -51,7 +53,7 @@ static inline uintptr_t round_down(uintptr_t value, size_t align_size)
return value & ~(align_size - 1);
}
/*
/**
* Returns value rounded up to the nearest multiple of align_size.
*/
static inline uintptr_t round_up(uintptr_t value, size_t align_size)
@ -59,26 +61,26 @@ static inline uintptr_t round_up(uintptr_t value, size_t align_size)
return (value + (align_size - 1)) & ~(align_size - 1);
}
/*
/**
* Seeds the psuedo-random number generator for my_cpu.
*/
void random_seed(int my_cpu, uint64_t seed);
/*
/**
* Returns a psuedo-random number for my_cpu. The sequence of numbers returned
* is repeatable for a given starting seed. The sequence repeats after 2^64 - 1
* numbers. Within that period, no number is repeated.
*/
testword_t random(int my_cpu);
/*
/**
* Calculates the start and end word address for the chunk of segment that is
* to be tested by my_cpu. The chunk start will be aligned to a multiple of
* chunk_align.
*/
void calculate_chunk(testword_t **start, testword_t **end, int my_cpu, int segment, size_t chunk_align);
/*
/**
* Flushes the CPU caches. If SMP is enabled, synchronises the threads before
* and after issuing the cache flush instruction.
*/

4
tests/tests.h
View File

@ -1,7 +1,9 @@
// SPDX-License-Identifier: GPL-2.0
#ifndef TESTS_H
#define TESTS_H
/*
/**
* \file
*
* Provides support for identifying and running the memory tests.
*
* Copyright (C) 2020-2022 Martin Whitaker.