Improve comments.

This commit is contained in:
Enrico Fraccaroli
2021-10-26 08:24:50 +02:00
parent 7a78333bae
commit 60a56e1139
9 changed files with 166 additions and 109 deletions
+28 -14
View File
@@ -1,5 +1,8 @@
@charset "UTF-8";
/* The standard CSS for doxygen 1.8.16 */
/* font families */
/* font sizes */
/* colors */
/* The following are overrides over hard-coded styles in Doxygen */
.sm-dox {
background: #4b5263; }
@@ -28,7 +31,10 @@ table,
div,
p,
dl {
font: 400 14px/22px Roboto, sans-serif;
font-size: 16px;
font-family: Roboto, Lucida, sans-serif;
font-weight: 400;
line-height: 22px;
display: block;
margin-block-start: 0em;
margin-block-end: 0em;
@@ -46,14 +52,20 @@ ul {
p.reference,
p.definition {
font: 400 14px/22px Roboto, sans-serif; }
font-size: 16px;
font-family: Roboto, Lucida, sans-serif;
font-weight: 400;
line-height: 22px; }
/* @group Heading Levels */
h1.groupheader {
font-size: 150%; }
.title {
font: 400 14px/28px Roboto, sans-serif;
font-size: 16px;
font-family: Roboto, Lucida, sans-serif;
font-weight: 400;
line-height: 22px;
font-size: 150%;
font-weight: bold;
margin: 10px 2px; }
@@ -216,7 +228,7 @@ pre.fragment {
overflow: auto;
word-wrap: break-word;
line-height: 125%;
font-family: monaco, Consolas, "Lucida Console", monospace;
font-family: Consolas, monospace, fixed;
font-size: 105%;
color: #A9B7C6; }
@@ -227,10 +239,9 @@ div.fragment {
color: #A9B7C6; }
div.line {
font-family: monospace, fixed;
font-size: 13px;
min-height: 13px;
line-height: 1.0;
font-family: Consolas, monospace, fixed;
font-size: 14px;
line-height: 18px;
text-wrap: unrestricted;
white-space: -moz-pre-wrap;
/* Moz */
@@ -471,7 +482,7 @@ table.memberdecls {
.memItemLeft,
.memItemRight {
font-family: monaco, Consolas, "Lucida Console", monospace; }
font-family: Consolas, monospace, fixed; }
.mdescLeft,
.mdescRight,
@@ -554,7 +565,7 @@ table.memberdecls {
box-shadow: 0 0 15px cyan; }
.memname {
font-family: monaco, Consolas, "Lucida Console", monospace;
font-family: Consolas, monospace, fixed;
font-weight: 400;
margin-left: 6px; }
@@ -716,7 +727,7 @@ div.directory {
font-family: Arial, Helvetica;
font-weight: bold;
font-size: 12px;
height: 14px;
height: 16px;
width: 16px;
display: inline-block;
background-color: #728DC1;
@@ -762,7 +773,10 @@ div.directory {
display: inline-block; }
table.directory {
font: 400 14px Roboto, sans-serif; }
font-size: 16px;
font-family: Roboto, Lucida, sans-serif;
font-weight: 400;
line-height: 22px; }
/* @end */
div.dynheader {
@@ -929,7 +943,7 @@ table.classindex {
padding: 0; }
div.ingroups {
font-size: 8pt;
font-size: 10pt;
width: 50%;
text-align: left; }
@@ -1269,7 +1283,7 @@ div.toc li.level4 {
#powerTip div {
margin: 0px;
padding: 0px;
font: 12px/16px Roboto, sans-serif; }
font: 12px/16px Roboto, Lucida, sans-serif; }
#powerTip:before,
#powerTip:after {
+46 -20
View File
@@ -7,11 +7,26 @@ $cyan-color: #56b6c2;
$yellow-color: #e5c07b;
$blue-color: #61afef;
$gutter-color: #4b5263;
// $code-font: "Courier New", Courier, "Lucida Sans Typewriter", "Lucida Typewriter", monospace;
$code-font: monaco,
Consolas,
"Lucida Console",
monospace;
/* font families */
$page-font-family: Roboto,
Lucida,
sans-serif;
$code-font-family: Consolas,
monospace,
fixed;
/* font sizes */
$title-font-size: 22px;
$page-font-size: 16px;
$code-font-size: 14px;
$page-line-height: $page-font-size+6px;
$code-line-height: $code-font-size+4px;
/* colors */
$title-fg-color: $white-color;
$title-bg-color: $black-color;
$menu-bg-color: $gutter-color;
@@ -69,7 +84,10 @@ table,
div,
p,
dl {
font: 400 14px/22px Roboto, sans-serif;
font-size: $page-font-size;
font-family: $page-font-family;
font-weight: 400;
line-height: $page-line-height;
display: block;
margin-block-start: 0em;
margin-block-end: 0em;
@@ -89,7 +107,10 @@ ul {
p.reference,
p.definition {
font: 400 14px/22px Roboto, sans-serif;
font-size: $page-font-size;
font-family: $page-font-family;
font-weight: 400;
line-height: $page-line-height;
}
@@ -100,7 +121,10 @@ h1.groupheader {
}
.title {
font: 400 14px/28px Roboto, sans-serif;
font-size: $page-font-size;
font-family: $page-font-family;
font-weight: 400;
line-height: $page-line-height;
font-size: 150%;
font-weight: bold;
margin: 10px 2px;
@@ -326,7 +350,7 @@ pre.fragment {
overflow: auto;
word-wrap: break-word;
line-height: 125%;
font-family: $code-font;
font-family: $code-font-family;
font-size: 105%;
color: $code-fg-color;
}
@@ -341,10 +365,9 @@ div.fragment {
}
div.line {
font-family: monospace, fixed;
font-size: 13px;
min-height: 13px;
line-height: 1.0;
font-family: $code-font-family;
font-size: $code-font-size;
line-height: $code-line-height;
text-wrap: unrestricted;
white-space: -moz-pre-wrap;
/* Moz */
@@ -651,7 +674,7 @@ table.memberdecls {
.memItemLeft,
.memItemRight {
font-family: $code-font;
font-family: $code-font-family;
}
.mdescLeft,
@@ -779,7 +802,7 @@ table.memberdecls {
}
.memname {
font-family: $code-font;
font-family: $code-font-family;
font-weight: 400;
margin-left: 6px;
}
@@ -1023,8 +1046,8 @@ div.directory {
font-family: Arial, Helvetica;
font-weight: bold;
font-size: 12px;
height: 14px;
width: 16px;
height: $page-font-size;
width: $page-font-size;
display: inline-block;
background-color: #728DC1;
color: white;
@@ -1074,7 +1097,10 @@ div.directory {
}
table.directory {
font: 400 14px Roboto, sans-serif;
font-size: $page-font-size;
font-family: $page-font-family;
font-weight: 400;
line-height: $page-line-height;
}
@@ -1272,7 +1298,7 @@ table.classindex {
}
div.ingroups {
font-size: 8pt;
font-size: 10pt;
width: 50%;
text-align: left;
}
@@ -1686,7 +1712,7 @@ tr.heading h2 {
#powerTip div {
margin: 0px;
padding: 0px;
font: 12px/16px Roboto, sans-serif;
font: 12px/16px $page-font-family;
}
#powerTip:before,
-1
View File
@@ -3,7 +3,6 @@
/// @brief Data structures concerning the Global Descriptor Table (GDT).
/// @copyright (c) 2014-2021 This file is distributed under the MIT License.
/// See LICENSE.md for details.
/// @addtogroup descriptor_tables Memory Management Modules
/// @brief GDT, IDT and TSS are all data structures specified by Intel x86
/// architecture in memory management module.
-1
View File
@@ -3,7 +3,6 @@
/// @brief Data structures concerning the Interrupt Descriptor Table (IDT).
/// @copyright (c) 2014-2021 This file is distributed under the MIT License.
/// See LICENSE.md for details.
/// @addtogroup descriptor_tables Descriptor Tables
/// @{
/// @addtogroup idt Interrupt Descriptor Table (IDT)
-1
View File
@@ -3,7 +3,6 @@
/// @brief Data structures concerning the Interrupt Service Routines (ISRs).
/// @copyright (c) 2014-2021 This file is distributed under the MIT License.
/// See LICENSE.md for details.
/// @addtogroup descriptor_tables Descriptor Tables
/// @{
/// @addtogroup isr Interrupt Service Routines (ISRs)
-1
View File
@@ -3,7 +3,6 @@
/// @brief Data structures concerning the Task State Segment (TSS).
/// @copyright (c) 2014-2021 This file is distributed under the MIT License.
/// See LICENSE.md for details.
/// @addtogroup descriptor_tables Descriptor Tables
/// @{
/// @defgroup tss Task State Segment (TSS)
+9 -1
View File
@@ -3,7 +3,12 @@
/// @brief Floating Point Unit (FPU).
/// @copyright (c) 2014-2021 This file is distributed under the MIT License.
/// See LICENSE.md for details.
/// @addtogroup devices Hardware Interfaces
/// @brief Data structures and functions for managing hardware devices.
/// @{
/// @addtogroup fpu Floating Point Unit (FPU)
/// @brief Device designed to carry out operations on floating-point numbers.
/// @{
#pragma once
#include "stdint.h"
@@ -124,3 +129,6 @@ void unswitch_fpu();
/// @brief Enable the FPU context handling.
/// @return 0 if fails, 1 if succeed.
int fpu_install();
/// @}
/// @}
+75 -69
View File
@@ -3,13 +3,18 @@
/// @brief Routines for interfacing with the Peripheral Component Interconnect (PCI).
/// @copyright (c) 2014-2021 This file is distributed under the MIT License.
/// See LICENSE.md for details.
///! @cond Doxygen_Suppress
/// @addtogroup devices Hardware Interfaces
/// @{
/// @addtogroup pci Peripheral Component Interconnect (PCI)
/// @brief Routines for interfacing with the peripherals.
/// @{
#pragma once
#include "stdint.h"
/// @defgroup pci_configuration_space The PCI configuration space.
/// @name PCI Configuration Space
/// @brief
/// The PCI Specification defines the organization of the 256-byte.
/// Configuration Space registers and imposes a specific template for the
/// space. Figures 2 & 3 show the layout of the 256-byte Configuration space.
@@ -19,65 +24,98 @@
/// functionality.
/// @{
/// 16 bits - Identifies the manufacturer of the device. Where valid IDs are
/// allocated by PCI-SIG (the list is here) to ensure uniqueness and 0xFFFF is
/// an invalid value that will be returned on read accesses to Configuration
/// Space registers of non-existent devices.
/// @brief Identifies the manufacturer of the device (16 bits). Where valid IDs are allocated by PCI-SIG (the list is here) to
/// ensure uniqueness and 0xFFFF is an invalid value that will be returned
/// on read accesses to Configuration Space registers of non-existent devices.
#define PCI_VENDOR_ID 0x00
/// 16 bits - Identifies the particular device. Where valid IDs are allocated
/// by the vendor.
/// @brief Identifies the particular device (16 bits).
#define PCI_DEVICE_ID 0x02
/// 16 bits - Provides control over a device's ability to generate and
/// respond to PCI cycles. Where the only functionality guaranteed to be
/// supported by all devices is, when a 0 is written to this register, the
/// device is disconnected from the PCI bus for all accesses except
/// Configuration Space access.
/// @brief Provides control over a device's ability to generate and
/// respond to PCI cycles (16 bits). Where the only functionality guaranteed to be supported by all
/// devices is, when a 0 is written to this register, the device is disconnected
/// from the PCI bus for all accesses except Configuration Space access.
#define PCI_COMMAND 0x04
/// 16 bits - A register used to record status information for PCI bus
/// related events.
/// @brief A register used to record status information for PCI bus related events (16 bits).
#define PCI_STATUS 0x06
/// 8 bits - Specifies a revision identifier for a particular device. Where
/// valid IDs are allocated by the vendor.
/// @brief Specifies a revision identifier for a particular device (8 bits).
#define PCI_REVISION_ID 0x08
/// 8 bits - A read-only register that specifies a register-level
/// programming interface the device has, if it has any at all.
/// @brief A read-only register that specifies a register-level
/// programming interface the device has, if it has any at all (8 bits).
#define PCI_PROG_IF 0x09
/// 8 bits - A read-only register that specifies the specific function the
/// device performs.
/// @brief A read-only register that specifies the specific function the
/// device performs (8 bits).
#define PCI_SUBCLASS 0x0a
/// 8 bits - A read-only register that specifies the type of function the
/// device performs.
/// @brief A read-only register that specifies the type of function the
/// device performs (8 bits).
#define PCI_CLASS 0x0b
/// 8 bits - Specifies the system cache line size in 32-bit units. A device
/// @brief Specifies the system cache line size in 32-bit units (8 bits). A device
/// can limit the number of cacheline sizes it can support, if a unsupported
/// value is written to this field, the device will behave as if a value of 0
/// was written.
#define PCI_CACHE_LINE_SIZE 0x0c
/// 8 bits - Specifies the latency timer in units of PCI bus clocks.
/// Specifies the latency timer in units of PCI bus clocks (8 bits).
#define PCI_LATENCY_TIMER 0x0d
/// 8 bits - Identifies the layout of the rest of the header beginning at
/// byte 0x10 of the header and also specifies whether or not the device has
/// multiple functions. Where a value of 0x00 specifies a general device, a
/// value of 0x01 specifies a PCI-to-PCI bridge, and a value of 0x02 specifies
/// a CardBus bridge. If bit 7 of this register is set, the device has
/// multiple functions; otherwise, it is a single function device.
/// @brief Identifies the layout of the header based on the type of device it
/// begins at byte 0x10 of the header (8 bits). A value of 0x00 specifies a general device, a value of 0x01 specifies
/// a PCI-to-PCI bridge, and a value of 0x02 specifies a CardBus bridge.
/// If bit 7 of this register is set, the device has multiple functions;
/// otherwise, it is a single function device.
#define PCI_HEADER_TYPE 0x0e
/// 8 bits - Represents that status and allows control of a devices BIST
/// (built-in self test).
/// @brief Represents that status and allows control of devices built-in self tests (8 bits).
#define PCI_BIST 0x0f
/// @defgroup pci_base_addresses The PCI base addresses.
/// @brief Points to the Card Information Structure and is used by devices that share silicon
/// between CardBus and PCI.
#define PCI_CARDBUS_CIS 0x28
/// @brief Points to the Subsystem Vendor ID
#define PCI_SUBSYSTEM_VENDOR_ID 0x2c
/// @brief Points to the Subsystem Device ID
#define PCI_SUBSYSTEM_ID 0x2e
/// @brief Bits 31..11 are address, 10..1 reserved
#define PCI_ROM_ADDRESS 0x30
/// @brief Points to a linked list of new capabilities implemented by the device. Used if bit 4 of the status register (Capabilities List bit) is set to 1.
/// The bottom two bits are reserved and should be masked before the Pointer
/// is used to access the Configuration Space.
#define PCI_CAPABILITY_LIST 0x34
/// @brief Specifies which input of the system interrupt controllers the device's
/// interrupt pin is connected to and is implemented by any device that makes
/// use of an interrupt pin. For the x86 architecture this register
/// corresponds to the PIC IRQ numbers 0-15 (and not I/O APIC IRQ numbers) and
/// a value of 0xFF defines no connection.
#define PCI_INTERRUPT_LINE 0x3c
/// @brief Specifies which interrupt pin the device uses. Where a value of 0x01 is INTA#, 0x02 is INTB#, 0x03 is INTC#,
/// 0x04 is INTD#, and 0x00 means the device does not use an interrupt pin.
#define PCI_INTERRUPT_PIN 0x3d
/// @brief A read-only register that specifies the burst period length, in 1/4
/// microsecond units, that the device needs (assuming a 33 MHz clock rate).
#define PCI_MIN_GNT 0x3e
/// @brief A read-only register that specifies how often the device needs access to
/// the PCI bus (in 1/4 microsecond units).
#define PCI_MAX_LAT 0x3f
/// @}
/// @name PCI Base Addresses
/// @brief
/// Base addresses specify locations in memory or I/O space.
/// Decoded size can be determined by writing a value of 0xffffffff to the
/// register, and reading it back. Only 1 bits are decoded.
@@ -90,40 +128,7 @@
#define PCI_BASE_ADDRESS_4 0x20 ///< Location of base address 4.
#define PCI_BASE_ADDRESS_5 0x24 ///< Location of base address 5.
/// @} pci_base_addresses
/// Points to the Card Information Structure and is used by devices that
/// share silicon between CardBus and PCI.
#define PCI_CARDBUS_CIS 0x28
/// Points to the Subsystem Vendor ID
#define PCI_SUBSYSTEM_VENDOR_ID 0x2c
/// Points to the Subsystem Device ID
#define PCI_SUBSYSTEM_ID 0x2e
/// Bits 31..11 are address, 10..1 reserved
#define PCI_ROM_ADDRESS 0x30
/// Points to a linked list of new capabilities implemented by the device.
/// Used if bit 4 of the status register (Capabilities List bit) is set to 1.
/// The bottom two bits are reserved and should be masked before the Pointer
/// is used to access the Configuration Space.
#define PCI_CAPABILITY_LIST 0x34
/// Specifies which input of the system interrupt controllers the device's
/// interrupt pin is connected to and is implemented by any device that makes
/// use of an interrupt pin. For the x86 architecture this register
/// corresponds to the PIC IRQ numbers 0-15 (and not I/O APIC IRQ numbers) and
/// a value of 0xFF defines no connection.
#define PCI_INTERRUPT_LINE 0x3c
/// Specifies which interrupt pin the device uses. Where a value of 0x01 is
/// INTA#, 0x02 is INTB#, 0x03 is INTC#, 0x04 is INTD#, and 0x00 means the
/// device does not use an interrupt pin.
#define PCI_INTERRUPT_PIN 0x3d
/// A read-only register that specifies the burst period length, in 1/4
/// microsecond units, that the device needs (assuming a 33 MHz clock rate).
#define PCI_MIN_GNT 0x3e
/// A read-only register that specifies how often the device needs access to
/// the PCI bus (in 1/4 microsecond units).
#define PCI_MAX_LAT 0x3f
/// @} pci_configuration_space
/// @}
#define PCI_PRIMARY_BUS 0x18 ///< Primary bus number.
#define PCI_SECONDARY_BUS 0x19 ///< Secondary bus number.
@@ -225,4 +230,5 @@ int pci_get_interrupt(uint32_t device);
/// @brief
void pci_debug_scan();
///! @endcond
/// @}
/// @}
+8 -1
View File
@@ -3,6 +3,11 @@
/// @brief Real Time Clock (RTC) driver.
/// @copyright (c) 2014-2021 This file is distributed under the MIT License.
/// See LICENSE.md for details.
/// @addtogroup drivers Device Drivers
/// @{
/// @addtogroup rtc Real Time Clock (RTC)
/// @brief Routines for interfacing with the real-time clock.
/// @{
#pragma once
@@ -13,4 +18,6 @@
extern void gettime(tm_t *time);
/// @brief Installs the Real Time Clock.
extern void rtc_install(void);
extern void rtc_install(void);
/// @}