Changeset da585a52 in mainline

Timestamp:

2005-05-11T18:58:54Z (19 years ago)

Author:

Martin Decky <martin@…>

Branches:

lfn, master, serial, ticket/834-toolchain-update, topic/msim-upgrade, topic/simplify-dev-export

Children:

d7568a9f

Parents:

93ca46f

Message:

doxygen-style comments

Location:

arch/ia32

Files:

• _link.ld (modified) (1 diff)
• src/asm.s (modified) (19 diffs)
• src/context.s (modified) (3 diffs)
• src/cpuid.s (modified) (3 diffs)
• src/userspace.c (modified) (2 diffs)

arch/ia32/_link.ld

@@ -1 @@
-/*
- *  ia32 linker script
+/** IA-32 linker script
  *  
  *  kernel text

arch/ia32/src/asm.s

@@ -27 +27 @@
 #
 
-# very low and hardware-level functions
+## very low and hardware-level functions
 
 .text
@@ -54 +54 @@
 .global memcmp
 
-#
-# set priority level high
+
+## Set priority level high
+#
+# Disable interrupts and return previous
+# EFLAGS in EAX.
+#
 cpu_priority_high:
         pushf
@@ -61 +65 @@
         cli
         ret
-    
-#
-# set priority level low
+
+
+## Set priority level low
+#
+# Enable interrupts and return previous
+# EFLAGS in EAX.
+#    
 cpu_priority_low:
         pushf
@@ -70 +78 @@
         ret
 
-#
-# restore priority level
+
+## Restore priority level
+#
+# Restore EFLAGS.
+#
 cpu_priority_restore:
         push 4(%esp)
@@ -77 +88 @@
         ret
 
-# return raw priority level
+## Return raw priority level
+#
+# Return EFLAFS in EAX.
+#
 cpu_priority_read:
         pushf
@@ -83 +97 @@
         ret
 
+
+## Halt the CPU
+#
+# Halt the CPU using HLT.
+#
 cpu_halt:
 cpu_sleep:
@@ -88 +107 @@
         ret
 
+
+## Turn paging on
+#
+# Enable paging and write-back caching in CR0.
+#
 paging_on:
         pushl %eax
@@ -99 +123 @@
         ret
 
+
+## Read CR3
+#
+# Store CR3 in EAX.
+#
 cpu_read_dba:
         movl %cr3,%eax
         ret
 
+
+## Write CR3
+#
+# Set CR3.
+#
 cpu_write_dba:
         pushl %eax
@@ -110 +144 @@
         ret
 
+
+## Read CR2
+#
+# Store CR2 in EAX.
+#
 cpu_read_cr2:
         movl %cr2,%eax
         ret
 
+
+## Enable local APIC
+#
+# Enable local APIC in MSR.
+#
 enable_l_apic_in_msr:
         pusha
@@ -126 +170 @@
         ret
 
+
+## Declare interrupt handlers
+#
+# Declare interrupt handlers for n interrupt
+# vectors starting at vector i.
+#
+# The handlers setup data segment registers
+# and call trap_dispatcher().
+#
 .macro handler i n
         push %ebp
@@ -170 +223 @@
 
 
+## I/O input (byte)
+#
+# Get a byte from I/O port and store it AL.
+#
 inb:
         push %edx
@@ -178 +235 @@
         ret
 
+
+## I/O input (word)
+#
+# Get a word from I/O port and store it AX.
+#
 inw:
         push %edx
@@ -186 +248 @@
         ret
 
+
+## I/O input (dword)
+#
+# Get a dword from I/O port and store it EAX.
+#
 inl:
         push %edx
@@ -194 +261 @@
         ret
 
+
+## I/O output (byte)
+#
+# Send a byte to I/O port.
+#
 outb:
         push %ebp
@@ -207 +279 @@
         ret
 
+
+## I/O output (word)
+#
+# Send a word to I/O port.
+#
 outw:
         push %ebp
@@ -220 +297 @@
         ret
 
+
+## I/O output (dword)
+#
+# Send a dword to I/O port.
+#
 outl:
         push %ebp
@@ -233 +315 @@
         ret
 
+
+## Copy memory
+#
+# Copy a given number of bytes (3rd argument)
+# from the memory location defined by 1st argument
+# to the memory location defined by 2nd argument.
+# The memory areas cannot overlap.
+#
 SRC=8
 DST=12
@@ -252 +342 @@
         ret
 
+
+## Fill memory with bytes
+#
+# Fill a given number of bytes (2nd argument)
+# at memory defined by 1st argument with the
+# byte value defined by 3rd argument.
+#
+DST=8
+CNT=12
+X=16
+memsetb:
+        push %ebp
+        movl %esp,%ebp
+        pusha
+    
+        cld
+        movl CNT(%ebp),%ecx
+        movl DST(%ebp),%edi
+        movl X(%ebp),%eax
+    
+        rep stosb %al,%es:(%edi)
+    
+        popa
+        pop %ebp
+        ret
+
+
+## Fill memory with words
+#
+# Fill a given number of words (2nd argument)
+# at memory defined by 1st argument with the
+# word value defined by 3rd argument.
+#
 DST=8
 CNT=12
@@ -271 +394 @@
         ret
 
-DST=8
-CNT=12
-X=16
-memsetb:
-        push %ebp
-        movl %esp,%ebp
-        pusha
-    
-        cld
-        movl CNT(%ebp),%ecx
-        movl DST(%ebp),%edi
-        movl X(%ebp),%eax
-    
-        rep stosb %al,%es:(%edi)
-    
-        popa
-        pop %ebp
-        ret
-
+
+## Compare memory regions for equality
+#
+# Compare a given number of bytes (3rd argument)
+# at memory locations defined by 1st and 2nd argument
+# for equality. If the bytes are equal, EAX contains
+# 0.
+#
 SRC=12
 DST=16

arch/ia32/src/context.s

@@ -36 +36 @@
 .global fpu_lazy_context_restore
 
+
+## Save current CPU context
 #
-# save context of this CPU
+# Save CPU context to the kernel_context variable
+# pointed by the 1st argument. Returns 1 in EAX.
+#
 context_save:
         push %ebx
@@ -59 +63 @@
         incl %eax
         ret
-    
+
+
+## Restore current CPU context
 #
-# restore saved context on this CPU
+# Restore CPU context from the kernel_context variable
+# pointed by the 1st argument. Returns 0 in EAX.
+#    
 context_restore:
         movl 4(%esp),%eax       # address of the kernel_context variable to restore context from
@@ -78 +86 @@
         xorl %eax,%eax          # context_restore returns 0
         ret
-
-

arch/ia32/src/cpuid.s

@@ -27 +27 @@
 #
 
-#
-# CPU identification functions.
 # The code below just interfaces the CPUID instruction.
 # CPU recognition logic is contained in higher-level functions.
@@ -38 +36 @@
 .global rdtsc
 
+
+## Determine CPUID support
+#
+# Return 0 in EAX if CPUID is not support, 1 if supported.
+#
 has_cpuid:
         push %ebx
@@ -56 +59 @@
         ret
 
-# cpuid(__u32 cmd, struct cpu_info *info)
+
+## Get CPUID data
+#
+# This code is just an interfaces the CPUID instruction, CPU recognition
+# logic is contained in higher-level functions.
+#
+# The C prototype is:
+#   void cpuid(__u32 cmd, struct cpu_info *info)
+#
+# @param cmd  CPUID command.
+# @param info Buffer to store CPUID output.
+#
 cpuid:
         pushl %ebp

arch/ia32/src/userspace.c

@@ -34 +34 @@
 #include <mm/vm.h>
 
+
+/** Enter userspace
+ *
+ * Change CPU protection level to 3, enter userspace.
+ *
+ */
 void userspace(void)
 {
@@ -48 +54 @@
             "iret"
             : : "i" (selector(UDATA_DES) | PL_USER), "i" (USTACK_ADDRESS+THREAD_STACK_SIZE-1000), "r" (pri), "i" (selector(UTEXT_DES) | PL_USER), "i" (UTEXT_ADDRESS));
-        /* NOT REACHED */
-
+        
+        /* Unreachable */
         for(;;);
 }