Wonderful Toolchain Wiki

User Tools

Site Tools

Trace:
wswan:tutorial:your_first_program

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Next revision		Previous revision
wswan:tutorial:your_first_program [2025/12/31 12:29] – created asiewswan:tutorial:your_first_program [2025/12/31 15:32] (current) – asie
Line 1: Line 1:
-===== Your first program ======+====== Your first program =======
  
-In this chapter, we're going to learn the basics of compiling and testing a WonderSwan homebrew project; by the end of it, we will write basic code to display something on the screen.+In this chapter, you're going to learn the basics of compiling and testing a homebrew project targetting the WonderSwan. 
 + 
 +===== Creating a project =====
  
 First, set up a new project: First, set up a new project:
  
-  $ mkdir 1-hellodisplay/ # (1)! +  $ mkdir first-program/ # (1)! 
-  $ wf-wswantool project new 1-hellodisplay/ # (2)!+  $ wf-wswantool project new first-program/ # (2)!
  
-  - Create the directory "1-hellodisplay" in the terminal's current working directory. +  - Create the directory "first-program" in the terminal's current working directory. 
-  - Create a new wswan targetting project with the directory and name "1-hellodisplay".+  - Create a new wswan target project with the directory and name "first-program".
  
-Next, compile the project:+Next, compile it:
  
-  $ cd 1-hellodisplay/+  $ cd first-program/
   $ make   $ make
  
-This will output the following lines:+The build script will output lines similar to the following:
  
   CC      src/main.c   CC      src/main.c
-  LD      build/1-hellodisplay_stage1.elf +  LD      build/first-program_stage1.elf 
-  ROM     1-hellodisplay.wsc+  ROM     first-program.wsc
   MERGE   compile_commands.json   MERGE   compile_commands.json
  
   - The C compiler is compiling the source file ''src/main.c''.   - The C compiler is compiling the source file ''src/main.c''.
-  - The ELF file ''build/1-hellodisplay_stage1.elf'' is being linked. This contains all of the program's source code and assets, but not yet at the correct memory locations. +  - The ELF file ''build/first-program_stage1.elf'' is being linked. This file will contain all of the program's source code and assets, but not yet placed in the console's ROM and RAM. 
-  - The ROM file ''1-hellodisplay.wsc'' is being created, now with the correct memory locations.+  - The ROM file ''first-program.wsc'' is being created, now with the correct memory placements.
   - The ''compile_commands.json'' file is being generated. This is used by your IDE to provide syntax highlighting; as a consequence, it is a good idea to run `make` after adding a new ''.c'' file to the project.   - The ''compile_commands.json'' file is being generated. This is used by your IDE to provide syntax highlighting; as a consequence, it is a good idea to run `make` after adding a new ''.c'' file to the project.
  
-Finally, you can run the ROM file using your emulator of choice. However, it's not displaying anything - after all, there's no code written yet.+Finally, you can run the ROM file using your emulator of choice. 
 + 
 +===== Editing source code ===== 
 + 
 +The program is not displaying anything - after all, there's no code written yet!
  
 Let's examine the ''src/main.c'' file: Let's examine the ''src/main.c'' file:
Line 45: Line 51:
 </code> </code>
  
-  - The default copyright header for the template file. This is required to inform you that you can use the example code contained without restrictions. However, before writing your own code, if you wish to put different terms on your code, you should remove it.+  - The default copyright header for the template file. This is required to inform you that you can use the example code contained therein without restrictions. However, before writing your own code, if you wish to put different terms on your code, you should remove it.
   - The ''wonderful.h'' include contains common CPU/target definitions. It's a good idea to put it in essentially every C file.   - The ''wonderful.h'' include contains common CPU/target definitions. It's a good idea to put it in essentially every C file.
   - The ''ws.h'' include contains hardware definitions specific to the WonderSwan, as well as many lower-level hardware abstraction functions.   - The ''ws.h'' include contains hardware definitions specific to the WonderSwan, as well as many lower-level hardware abstraction functions.
Line 52: Line 58:
 Pay special attention to the `while(1);` at the end - this is an infinite loop. Pay special attention to the `while(1);` at the end - this is an infinite loop.
          
-You may be used to ending `main()` with a `return;` of some type. On bare metal, however, one should not return from main, as there's no operating system to return to. Removing it will cause the system to jump to arbitrary code with unforeseen consequences!+You may be used to ending `main()` with a `return;` of some type. On bare metal, however, one should not return from main, as there's no operating system to return to. Removing it will cause the system to jump to arbitrary code, with unforeseen consequences!
 </WRAP> </WRAP>
  
 With only an infinite loop in ''main'', it's clear that the code won't do anything. Let's make it do something! With only an infinite loop in ''main'', it's clear that the code won't do anything. Let's make it do something!
 +
 +===== Throwing shade =====
  
 For now, we're going to assume a "mono" program - we'll introduce the color mode in a later chapter. On the "mono" WonderSwan, the palette pipeline that converts tile information to display shades consists of two parts: the //palette//, mapping each of the four possible palette //indexes// to one of eight color values; and a //shade look-up table//, mapping each of the color values to one of the sixteen total shades which the panel can display. For now, we're going to assume a "mono" program - we'll introduce the color mode in a later chapter. On the "mono" WonderSwan, the palette pipeline that converts tile information to display shades consists of two parts: the //palette//, mapping each of the four possible palette //indexes// to one of eight color values; and a //shade look-up table//, mapping each of the color values to one of the sixteen total shades which the panel can display.
Line 71: Line 79:
 </code> </code>
  
-This sets a default table, with the color value ''0'' corresponding to the brightest shade (''0'') and ''7'' to the darkest shade (''15'').+This sets a default shade look-up table, with the color value ''0'' corresponding to the brightest shade (''0'') and ''7'' to the darkest shade (''15'').
  
 <WRAP round info> <WRAP round info>
-As the "mono" WonderSwan's panel is a monochrome LCD, it's shades with //higher// values which are darker; note that the opposite is true for the WonderSwan Color's RGB values.+As the "mono" WonderSwan's panel is a monochrome LCD, it's shades with //lower// values which are brighter. The opposite is true for the WonderSwan Color's RGB values.
 </WRAP> </WRAP>
  
Line 88: Line 96:
 while (1) { while (1) {
     outportw(WS_SCR_PAL_0_PORT, inportw(WS_SCR_PAL_0_PORT) + 1); // (1)!     outportw(WS_SCR_PAL_0_PORT, inportw(WS_SCR_PAL_0_PORT) + 1); // (1)!
-    ws_delay_ms(100); // (2)!+    ws_delay_ms(1000); // (2)!
 } }
 </code> </code>
  
   - This loads the first palette, adds one to it, and saves it. As the lowest bits constitute the color value for the first palette index, this will cause the background color to change on every execution.   - This loads the first palette, adds one to it, and saves it. As the lowest bits constitute the color value for the first palette index, this will cause the background color to change on every execution.
-  - As we don't have any interrupts set up yet, the only thing we can do is busy-wait - that is, stall the CPU for a specified number of microseconds. While this is not recommended for production code, it's simple enough to prevent rapid flicker in the demonstration.+  - As we don't have any interrupts set up yet, the only thing we can do is busy-wait - that is, stall the CPU for a specified number of milliseconds.
  
 That's all! Compile the code using ''make'' and run it in your emulator of choice. If done correctly, you should see the display slowly change colors from brightest to darkest and back again. That's all! Compile the code using ''make'' and run it in your emulator of choice. If done correctly, you should see the display slowly change colors from brightest to darkest and back again.
  
wswan/tutorial/your_first_program.1767184197.txt.gz · Last modified: by asie