Tuesday, November 15, 2022

Golang Cheat Sheet II

In the previous post, we checked out Go as a statically typed and compiled programming language designed at Google. Go is gaining popularity due to its ability to deliver highly scalable concurrent computing software.

Development teams prefer Golang to harness the power of large servers and sophisticated cloud platorms. Go can be used in mobile, web and simple game development and can also invoke C code directly via Cgo.

Let's check it out!

Example
In the previous post, we created a simple Hello World example by setting up the development environment, create a Go module with the code and issue go build and run commands to execute the Hello World program

Modules
A module in Go is a collection of Go packages stored in a file tree with a go.mod file at its root The go.mod file defines the module's path, which is also the import path used for the root directory, and its dependency requirements which are other modules needed for a successful build.

A module is defined by a UTF-8 encoded text file named go.mod in its root directory. Here are some usages:
 go get  Updates module dependencies in the go.mod file
 go install  Builds and installs the packages named by paths
 go list -m  Lists all the modules instead of all the packages
 go mod download  Downloads named modules into the module cache
 go mod init  Initializes + writes new go.mod file in the current directory
 go mod tidy  Ensures the go.mod file matches source code in the module

Packages
Go programs are built by linking together packages. A package is constructed from one or more source files that declare constants, types, variables and functions belonging to the package to which are accessible in all files of the sams package. Those elements may be exported and used in other package(s).

Functional Programming
Functional programming is the paradigm that treats computation as the evaluation of functions and avoids state and mutable data as opposed to imperative programming which empathizes change of state. Without shared data, concurrency becomes easier because this means no locks, race conditions, no dead locks etc.

Concurrency
Concurrency is the "composition of independently executing computations". Concurrency: dealing with lots of things at once but parallelism: about doing lots of things at once. Concurrency is all about structure whereas parallelism is about execution. Consequently, Golang provides first-class language support for concurrency.

Challenges in concurrent programming include co-ordinating tasks + shared memory. Thus, Go concurrency implementation centers around goroutines: functions that execute simultaneously in Go program with other (goroutine) functions and are lightweight threads managed by the Go runtime. Here are some more terms:

 Concurrency  Ability to have multiple things that can be worked on not necessarily at the same time
 Parallelism  Ability to work on multiple concurrent tasks typically all worked on at the same time
 Process  Part of the Operating System resposible for executing an application
 Thread  Unit within the process which executes the code inside an application
 Goroutines  Special function type that can run while other goroutines are running
 WaitGroups  Allows a supervising goroutine to wait on several other go routines
 Mutexes  Allow us to share memory between go routines and our application
 Channels  Another mechanism available to us to coordinate the work between multiple goroutines

Concurrency in Go is also based on Communicating Sequential Processes. CSP is a form to describe patterns of interaction in concurrent systems. CSP involvement in concurrency based on messaging passing channels. Channels in Go allow goroutines to communincate with each other safely + co-ordinate work between them.

Demos
 Introduction  Goroutine ID
 Goroutines  Sequential code, Creating goroutines
 Sync Package  Using WaitGroups, Mutexes, Read/Write Mutexes
 Channels  Unbuffered channels, Buffered channels, Channel types
 Working with closed channels, Using select statements

IMPORTANT
If you are new to goroutines then you may like to log go ID() similar to logging thread ID in multithreading:
go mod init goidtesting
go get "github.com/nikandfor/goid"
go mod tidy
main.go
package main
import (
	"fmt"
	"os"
	"time"
	"github.com/nikandfor/goid"
)
func say(s string) {
	for i := 0; i < 5; i++ {
		time.Sleep(100 * time.Millisecond)
		_, _ = fmt.Fprintln(os.Stdout, goid.ID(), s)
	}
}
func main() {
	go say("world")
	say("hello")
}
Data Race
A data race occurs when two goroutines access the same variable concurrently and are very hard to debug:
 go run -race mysrc.go // to run the source file
 go build -race mycmd // to build the command
 go install -race mypkg // to install the package
 go test -race mypkg // to test the package

Unit Testing
Unit testing in Golang uses the testing package however more sophisticated Test Driven Design TDD / BDD can be accomplished using the Ginkgo testng framework complemented by the Gomega matching library.

However, unit testing concurrent code in Go is more challenging esp. anonymous goroutines as they are not executed immediately. Instead the calling thread keeps execution priority until it pauses. Only then will the code inside the goroutine get execution. Therefore, a solution could be insert an empty function which acts as a hook for testing purposes; push a value into a channel which blocks until received + TEST code passes.

Cloud Computing
Cloud computing systems are highly scalable that require access to resources which must be shared. Thus, Golang has the capability to develop highly scalable, highly performant, reliable and concurrent applications.

Consequently, Go is often preferred to build tools for distributed systems and containerized applications such as Docker and Kubernetes because of Go's fast compilation, low-level system calls and concurrency features.

Cgo
Cgo lets Go packages call C code. Cgo outputs Go and C files that can be combined into a single Go package.

Hello World
 hello.go  hello.h  hello.c
 package main
 import "fmt"

 // #include "hello.h"
 import "C"

 func main() {
 	fmt.Println("begin")
 	C.hello()
 	fmt.Println("-end-")
 }
 #ifndef _HELLO_H_
 #define _HELLO_H_

 #include <stdio.h>

 void hello();

 #endif//_HELLO_H_
 #include "hello.h"

 void hello()
 {
     fprintf(stderr, "%s\n", "Hello Cgo!");
 }
According to this thread, it is possible to debug Go to C from Visual Studio Code on Linux. Assuming you can F5 run the project then set breakpoints either side the Go code calling into and out of the C function to step.


Mod Security
In the previous post, we coded an example in Go from scratch as full end-to-end Web API demo on our local host, in Docker and on Kubernetes. Extend this example as Web Application Firewall using Mod Sec and Cgo.

Install Mod Security on local host
 git clone --depth 1 -b v3/master --single-branch https://github.com/SpiderLabs/ModSecurity
 cd ModSecurity
 git submodule init
 git submodule update
 ./build.sh
 ./configure
 make
 sudo make install
Follow all instructions from the example i.e. download OWASP rules, build main, server and waf code. Here, it is critical for Go to C interface to set include + linker flags correctly avoiding runtime PATH for shared libs!

waf.go
 package waf
 // #cgo CFLAGS: -I/usr/local/modsecurity/include
 // #cgo LDFLAGS: -L/usr/local/modsecurity/lib/ -Wl,-rpath -Wl,/usr/local/modsecurity/lib/ -lmodsecurity
 // #include "waf.h"
 import "C"

Asm
Finally, if you would like to reproduce Go example that calls ASM assembly code then replicate goid source:
 main.go  goid_amd64.s
 package main
 import (
 	"fmt"
 	"goidtesting/goid"
 	"os"
 	"time"
 )
 func say(s string) {
 	for i := 0; i < 5; i++ {
 		time.Sleep(100 * time.Millisecond)
 		_, _ = fmt.Fprintln(os.Stdout, goid.ID(), s)
 	}
 }
 func main() {
 	go say("world")
 	say("hello")
 }
 #include "textflag.h"

 TEXT ·ID(SB), NOSPLIT, $0-8
 	MOVQ	(TLS), AX     // AX = getg()
 	MOVQ	0x98(AX), AX   // AX = AX.goid
 	MOVQ	AX, ret+0(FP) // ret = AX
 	RET

Summary
To summarize, Go is now popular due to its ability to deliver highly scalable concurrent computing software. Plus, Cgo also allows Go programs to interoperate with C libraries, distributed cloud computing, and eBPF.

Therefore, writing low level C code to target 8-bit Sega Master System hardware and 16-bit Sega Mega Drive has proved to be very valuable experience for Cgo applications which could assist in Go + Cloud Computing!

Thursday, September 15, 2022

Golang Cheat Sheet

Golang is a statically typed and compiled programming language designed at Google. Go plays a major role in Enterprises by developing highly scalable concurrent cloud computing systems like Docker + Kubernetes.

Let's check it out!

Installation
Download and install Go as per instructions for your target operating system. Afterwards verify go version.

Windows
Download and open the Go MSI file. Follow all prompts and ensure Go added to PATH environment variable.

Mac OS/X
Download and open the Go PKG file. Follow all prompts and ensure Go added to PATH environment variable.

Linux
Download and extract the Go archive. Launch Terminal and ensure Go added to PATH environment variable.
 sudo rm -rf /usr/local/go
 sudo tar -C /usr/local -xzf go1.18.3.linux-amd64.tar.gz
 export PATH=$PATH:/usr/local/go/bin/
 go version
Alternatively, include export PATH="$PATH:/usr/local/go/bin/" to your ~/.bashrc file for future use.

IMPORTANT
If Go does not install or update then you may have to remove snap package using sudo snap remove go. Also, verify Go environment variables by entering go env at the Terminal prompt for all operating systems.

Uninstall
Follow this guide on how to uninstall Go. While there seems to be many options, the following should work:
 sudo apt-get remove golang-go
 sudo apt-get remove --auto-remove golang-go

IDEs
Now we'd like to build Golang software so let's setup 2x main Integrated Development Environments IDEs:

VS Code
Visual Studio Code is a popular lightweight IDE available cross platform on Windows, Mac OS/X and Linux. Install VS Code and install the following plugins: Go, Go Doc, Go Outliner, Go Autotest + Go Test Explorer.
 Go  Rich Go language support for Visual Studio Code
 Go Doc  Show Go's documentation symbols and packages
 Go Outliner  Go code outline explorer and navigation package
 Go Autotest  Adds autotest functionality to vscode's Go mode
 Go Test Explorer  Go Test Explorer for unit and integration testing

Launch VS Code. Press Ctrl + Shift + P. Filter on "Go: Install". Choose "Go: Install/Update Tools". Select all. Ok. Also, if prompted "The "gopls" command is not available." bottom right then click Install to go get gopls.

Miscellaneous
Launch Terminal. Drag tab headings to prefer following order: Terminal, Problems, Output, Debug Console.

Mappings
If you are transitioning from Windows to Linux you may like to update keyboard mappings for example Back to Alt + LeftArrow. File | Preferences | Keyboard Shortcuts. Filter "Go Back". Click pencil. Hit Alt + LeftArrow.

Repeat process for Terminal: Copy Selection: File | Preferences | Keyboard Shortcuts. Hit Ctrl + C and Enter. Repeat process for Terminal: Paste into Active Terminal: File | Preferences | Keyboard Shortcuts. Hit Ctrl + V.

Navigation
If you are transitioning from Visual Studio on Windows to VS Code then the Solution Explorer with folders being represented as folder icons not arrows may be more familiar. Therefore, install vscode-icons plugin. Also, as code bases become larger it can be handier to install the Bookmarks plugin for easier navigation.

Shortcuts
 Ctrl + ,  Open Settings similar to Preferences  F5  Debug | Start w/ Debugging
 Ctrl + P  Search files to open e.g. main.go  Ctrl + F5  Debug | Run w/o Debugger
 Ctrl + R  Select to open from previous files  F9  Debug | Toggle Breakpoint
 Ctrl + Shift + O  Outline file structure for opened file  F10  Debug | Step Over
 F12  Navigate | Go to Definition  F11  Debug | Step Into
 Alt + Left  Navigate | Going Backward  Shift + F11  Debug | Step Out

Zoom In
Finally, you may like to Ctrl + "+" to zoom in on the Explorer and Terminal then reduce the Font Size to 12.


GoLand
GoLand is a cross-platform Go Integrated Development Environment IDE on Windows, Mac OS/X and Linux. Install GoLand and setup the following configurations as commercial alternative with better IDE Intellisense.

Configurations
Launch GoLand. In the "Welcome to GoLand" popup choose Customize | Color theme | IntelliJ Light. Next, choose All settings... Expand Go tab at the top | GOROOT | Add SDK... Local | Navigate to where Go was installed previously e.g. /usr/local/go. Finally update GOPATH. Click "+" select ~/go. OK | Apply | OK.


IMPORTANT
Verify GOROOT path is correct from Terminal via go env | grep GOROOT. Repeat for go env | grep GOPATH. Also, in Go tab | Go Modules ensure "Enable Go modules integration" is checked as may not be by default.


Mappings
Align GoLand Keymap to VS Code Keymap for consistent keyboard shortcuts and developer IDE experience. In the "Welcome to GoLand" popup choose Plugins | VSCode Keymap | Install. Navigate back to Customize. Under Keymap change the default value to VSCode. Now all VS Code shortcuts above will work in GoLand.

Additionally to Ctrl + Shift + O, outline file structure for opened file, GoLand has these handy shortcuts also:
 Ctrl + Numpad -  Collapse struct types for easier overall type visibility in IDE
 Ctrl + Numpad +  Expand struct types to navigate type properties + methods

NOTE
If Ctrl + Shift + O launches Symbols then remove duplicate: Choose Settings | Keymap | filter as "symbol". Double click Navigate | Go to Symbol | Edit | Remove Ctrl+Shift+O | Apply | OK. Repeat this as necessary.

Settings
Finally, from Customize | All settings... here are some more general GoLand IDE settings that can be useful:
 Editor | General | Code Folding | Fold by default | General  UNCHEKED
 Editor | Font  JetBrains Mono | Size: 14.0 | Line: 1.2
 Editor | Color Scheme Font  Scheme: Classic Light
 Editor | Inspections | Proofreading | Typo  UNCHEKED

Example
Create the obligatory Hello World program in both VS Code and GoLand IDE to complete the configration:

main.go
package main
import "fmt"

func main() {
	fmt.Println("Hello World!")
}

VS Code
Create "HelloVSCode" folder at ~/go/src. Launch VS Code. Open folder [Ctrl+K, Ctrl+O] HelloVSCode folder. New File | main.go. Enter + save Hello World source code from package main above. Launch new Terminal:
go mod init HelloVSCode
go mod tidy

go build .
go run .
Set breakpoint in main.go. Run menu and choose either Start Debugging or Run without Debugging option.


GoLand
Launch GoLand. New Project | Enter Location and GOROOT as above i.e. Go 1.18.3 /usr/local/go. Create.

 Location  ~/go/src/HelloGoLand
 GOROOT  Go 1.18.3 /usr/local/go
 Enable vendoring support automatically  CHECKED

In main.go right click triangle next to func main() | Modify Run configuration... Ensure there are no errors. If there are errors then ensure if Run kind is Package the package name matches in go.mod. Otherwise choose File | main.go. Once confirmed no errors then right click triangle and choose the Run or Debug configuration.

Cache
If GoLand complains "cannot resolve symbol" then choose File | Invalidate Caches... | Invalidate and Restart.

Configurations
Track active item in solution explorer similar to Visual Studio: Click cog to right of Project and Always Select Opened File. Hit shift key twice for quick search. Remember Rename files and folder is in the Refactor menu!

Layout
It may be good idea to position Problems tab next to code window so you can see issues as you enter code. In GoLand, click cog on Problems | Move to | Right Top. In VS Code right click Problems | Move Panel Right.

Navigation
As code bases become larger use the Bookmarks feature for easier navigation. Right click the code gutter + Add Bookmark. View menu | Tool Windows | Bookmarks. This can also be used to edit/remove Breakpoints.

Source Control
In GoLand, by default the Staging area may be disabled. Therefore, you wouldn't see any Unversioned files To disable changelists choose File menu | Settings | Version Control | Git | Enable staging area | UNCHECK.

In GoLand, top right under Project is the Control tab. Right click any file and choose Rollback to revert any changes. In VS Code the Source Control tab is third tab. Choose Discard Changes as corresponding action.


Summary
To summarize, we have a simple setup for Golang programming on Windows, Mac OS/X and Linux. There is much to explore e.g. Cloud Computing and developing highly scalable concurrent applications using Golang!
This will be topic of the next post.

Wednesday, August 31, 2022

Linux Setup Cheat Sheet III

In the previous post, we set up Ubuntu Linux on Windows and Mac OS/X using VirtualBox. Now we focus our set up on dedicated Ubuntu Linux workstation or Windows PC that has dual boot with Ubuntu Linux installed.

Let's check it out!

Account
Typically, during the installation process, an admin account is prompted to be created with username and password. However, follow these instructions to add new user account with admin access on Ubuntu Linux.
 adduser stevepro
 usermod -aG sudo stevepro
 id stevepro
 su - stevepro

Alternatively, manage user accounts from Settings | Users user interface to add new user account. Initially, the account user will use the default icon. Consider changing via Settings | Users | Picture | Select File.

Login
If, whenever you attempt to login, you get the Ubuntu black screen with flashing cursor then attempt this fix: Reboot computer and login as recovery mode. Once logged in again, download and install NVIDIA.run.

Checkout here and here how to install nVidia driver on Ubuntu Linux e.g. NVIDIA-Linux-x86_64-460.84.run
 sudo su
 cd Downloads
 ./NVIDIA.run

IMPORTANT
If you are running X server then you may get an error when trying to install NVIDIA.run while still logged in:
 Ensure you are logged out!
 sudo service lightdm stop
 sudo init 3
 ./NVIDIA...run
 sudo service lightdm start

In, Software Updater | Additional Drivers, ensure NVidia is set "Using X.Org X server" as alternative driver.


Graphics
Initially, video file formats like mp4 may result in black screen. If so then install all the Multimedia Codecs:
 sudo apt-get update
 sudo apt install ubuntu-restricted-extras

Ubuntu
Confirm the version of Ubuntu Linux installed on terminal with lsb_release -a. Upgrade now accordingly:
 sudo apt update && sudo apt upgrade
 sudo reboot command
 sudo apt install update-manager-core
 sudo do-release-upgrade
 sudo reboot
 lsb_release -a

Kernel
Mainline is graphical tool to install the latest mainline kernel in Ubuntu Linux. Install Mainline from Terminal:
 sudo add-apt-repository ppa:cappelikan/ppa
 sudo apt update
 sudo apt install mainline
 mainline --check
 mainline --list
Start | Ubuntu Mainline. From the User Interface now install / uninstall Ubuntu Linux versions seemlessly. Once Ubuntu Linux kernel has been updated confirm kernel new version with uname -r.

Diff Tools
On Windows PC, Tortoise Merge is handy tool to compare 2x files whereas WinMerge is handy tool that can compare 2x directories. Meld + KDiff3 are alternatives for Linux both installed from Ubuntu Software Center.

Meld
File | New Comparison. File comparison navigate to file 1. Directory comparison navigate to file 2. Compare.

KDiff3
Similar to WinMerge: A. Directory navigate to directory 1. B. Directory navigate to directory 2. Compare OK.

Disk Space
Use Ubuntu Linux Disk Analyzer utility to identify common locations which can be used to free up disk space:
 rm -rf ~/.local/share/Trash/*
 du -sh ~/.cache/thumbnails
 sudo du -h /var/lib/snapd/snaps
 sudo du -sh /var/cache/apt
 sudo apt-get autoclean
 sudo apt-get clean
 sudo journalctl --disk-usage
 sudo journalctl --vacuum-time=3d
Other utilities to identify excess storage include ncud and bleachbit both which can be sudo apt install[ed].

Find
Here are some simple but effective uses of the find command e.g. find all text in file that follows predicate:
 find -L . -type f -exec grep -HniI 'g++' {} \; > ~/Steven/gpp.txt

Another useful example is how to find all of the distinct file extensions in a particular folder hierarchy:
 find . -type f | perl -ne 'print $1 if m/\.([^.\/]+)$/' | sort -u

Shortcuts
 General  Minimize all windows  Ctrl + Alt + D
 gedit  Move prev tab  Ctrl + Alt + PgUp
 gedit  Move next tab  Ctrl + Alt + PgDown

SSH
Secure SHell [SSH] may not be enabled after Ubuntu Linux is installed. Therefore you may get the following:
 ssh stevepro@192.168.15.50
 ssh: connect to host 192.168.15.50 port 22: Connection refused

Server
Here is how to fix the Connection refused issue on port 22. On the destination server set up the following:
 # Make sure OpenSSH is installed
 # Install SSH
 # Check SSH service
 # Start SSH service
 sudo apt list --installed | grep openssh-server
 sudo apt install openssh-server
 sudo service ssh status
 sudo service ssh start

Client
On source client connect to Files | Other Locations | Connect to Server sftp://stevepro@192.168.15.50.
Also, ssh stevepro@192.168.15.50 should now work!

Mouse Scroll
After setting up new blue tooth mouse the default scroll was too slow. Therefore, install and set up lmwheel:
 sudo apt-get install imwheel

Create mouse.sh. Integrate the following shell script. Set execute permissions. Configure using ./mouse.sh.
#!/bin/bash
if [ ! -f ~/.imwheelrc ]
then
cat >~/.imwheelrc<<EOF
".*"
None,      Up,   Button4, 1
None,      Down, Button5, 1
Control_L, Up,   Control_L|Button4
Control_L, Down, Control_L|Button5
Shift_L,   Up,   Shift_L|Button4
Shift_L,   Down, Shift_L|Button5
EOF
fi
CURRENT_VALUE=$(awk -F 'Button4,' '{print $2}' ~/.imwheelrc)
NEW_VALUE=$(zenity --scale --window-icon=info --ok-label=Apply --title="Wheelies" --text "Mouse wheel speed:" --min-value=1 --max-value=100 --value="$CURRENT_VALUE" --step 1)
if [ "$NEW_VALUE" == "" ];
then exit 0
fi
sed -i "s/\($TARGET_KEY *Button4, *\).*/\1$NEW_VALUE/" ~/.imwheelrc # find the string Button4, and write new value.
sed -i "s/\($TARGET_KEY *Button5, *\).*/\1$NEW_VALUE/" ~/.imwheelrc # find the string Button5, and write new value.
cat ~/.imwheelrc
imwheel -kill

VNC Viewer
If you are transitioning from Windows to Linux you may like to remote desktop from Windows to Linux box.

Linux
Follow all instructions. Change Ubuntu desktop manager from GNOME to LightDM. Install X11VNC as service on Ubuntu. Launch Terminal and enter the following. When prompted, ensure you choose lightdm not gdm3:
sudo apt-get update
sudo apt-get install lightdm
sudo reboot
sudo apt-get install x11vnc

After installing LightDM, rebooting and installing X11VNC, configure x11vnc.service. Replace your password!
sudo gedit /lib/systemd/system/x11vnc.service

[Unit]
Description=x11vnc service
After=display-manager.service network.target syslog.target

[Service]
Type=simple
ExecStart=/usr/bin/x11vnc -forever -display :0 -auth guess -passwd REPLACE_WITH_YOUR_LOGIN_PASSWORD
ExecStop=/usr/bin/killall x11vnc
Restart=on-failure

[Install]
WantedBy=multi-user.target

Finally, after configuring x11vnc.service, enter the following commands to complete the VNC Viewer setup.
systemctl daemon-reload
systemctl enable x11vnc.service
systemctl start x11vnc.service

systemctl status x11vnc.service
ip addr | grep 192                        # NOTE the IP address 192.168.1.X

IMPORTANT
Don't lock the screen as you won't be able to VNC back in! Change Settings | Privacy | Screen Lock to this:
Windows
Download and install VNC Viewer. Launch VNC Viewer. Setup Team. Choose File | New Connection. Enter the IP address from above on port 5000 for VNC Server e.g. 192.168.1.X:5900. Enter friendly name + Connect.

When prompted choose Continue. Enter password | Check Remember password. Unfortunately not all keys may work e.g. Caps Lock. Also, you may have to disable and re-enable Repeat Keys from Universal Access.

Summary
Now we have a dedicated Ubuntu Linux workstation set up we are all set for cloud computing development!

Thursday, August 4, 2022

Skazka Code Complete

Skazka is a Slavic RGP Adventure game originally written in BASIC for Sega SC-3000 and posted to SC-3000 Survivors Facebook group. The source code is now ported to C using devkitSMS for the Sega Master System.

Let's check it out!

Note: Skazka development based on devkitSMS Programming Setup and devkitSMS Programming Sample.
Download source code here.


Instructions
Skazka captures the core mechanics of old school RPG experience: Kill monsters | level up | upgrade gear. There are 5x different enemies in increasing order: Razboynik, Hungry Wolf, Kikimora, Leshy, Baby Yaga. Defeat final boss Koschey to beat the game!

Tools
Here is a list of Tools and frameworks that were used in the development of this project:
 KEY  VALUE
 Programming  devkitSMS
 Compiler  sdcc 3.6.9
 Assembler  WLA-DX
 IDE  Visual Studio 2015 / Visual Studio Code
 Languages  C / Z80
 Graphics  BMP2Tile 0.43 / BMP Converter / GIMP 2
 Music  pcmenc / vgm2psg
 Emulators  Emulicious / Fusion / Meka
 Debugger  Emulicious Debugger

ROM Hacking
You can hack this ROM! Download and dump Skazka into Hex Editor, e.g. HxD, and modify bytes:
 ADDRESS  VARIABLE  DESCRIPTION
 0x019E  Delay  Used to speed through any game delay.
 0x019F  Invincible  Non-zero value enables invincibility.
 0x01A0  Current XP  Non-zero sets current experience pts.
 0x01A1  Current HP  Non-zero sets default healthy points.
 0x01A2  Set Gold  Non-zero sets current gold available.
 0x01A3  Set Weapon  Set value to 1 or 2 for stock else 0.
 0x01A4  Set Armor  Set value to 1 or 2 for armor else 0.
 0x01A5  Add Life  Set value to 1=Life otherwise 0=None.
 0x01A6  Village Talk  Set value to 1=repeat villagers talk.
 0x01A7  Music Off  Set 0=Music to play otherwise silent.
 0x01A8  Sound Off  Set 0=Sound to play otherwise silent.

Hints
  • Try to buy weapon "Sword" or armor "Tegilay" with your initial gold before entering any forest fights.
  • After completing each forest fight, ensure you "Rest" at the main screen to replenish all health points.
  • In the shop when you buy items you already have then will be deducted unconditionally so be aware!
  • Get "+1 Life" just in case you lose a fight or the final boss battle so you do not have to restart game.
  • Maximize HP + XP + get the best weapon "Axe" and best armor "Kolchuga" before fighting the boss.
  • Fight boss when you have > 60 XP because your weapon and armor may be slightly more powerful!

Cheats
  • On title screen, hold fire2 to skip intro music. Same applies on boss and over screens.
  • On title screen, hold fire2 after intro music completes to reveal hidden credits screen.
  • On stats screen, move joystick left or right to skip over the flashing arrows indication.
  • In Easy mode forest screen, press fire2 to "Run away" without risking losing any HPs.

Debugging
  • On Windows you can debug the source code directly from in Visual Studio Code after pressing F5.
  • On Linux you can debug source code directly from Visual Studio Code but launch Emulicious first.

Credits
Extra special thanks to sverx for the devkitSMS. Plus StevePro Studios would like to thank Calindro all for his 24/7 Tech Support. Plus shout out to Mojon Twins na_th_an in which I found lots of some cool sound effects.

Update
Skazka V1.0 was initially a text-based RPG adventure game. However, after collaboration with Kagesan from SMS Power!, graphics were added for all screens for V2.0 which is the most up-to-date version of the game.



Summary
Despite the fact that Skazka was a simple text-based RPG adventure with limited game play, the cool aspect was collaborating with original developer and working together to port the game to the Sega Master System.

Skazka was entered in the SMS Power! 2022 competition to connect the Sega SC-3000 Facebook group and the SMS Power! community with the goal to spread Sega 8-bit preservation and fanaticism. That's awesome!

Monday, July 4, 2022

devkitSMS Programming Sample V

In the previous post, we checked out devkitSMS Programming Setup II. The devkitSMS provides tools and code to support many homebrew development projects for the Sega Master System and Sega Game Gear.

The latest version of the devkitSMS requires an updated version of Small Device Cross Compiler SDCC 4.x and supports new and updated features including the ability to page both code and content transparently.

Let's check it out!

Software
Follow all instructions from the previous post: this documents how to setup the pre-requisite software.
Note: ensure you have downloaded and installed the devkitSMS and Small Device C Compiler [SDCC].

Also ensure that pcmenc is installed in the SDCC bin folder as this utility is used to play WAV audio files.

Demo
All demos in this devkitSMS programming sample are based on the simple Hello World program the previous post that utilizes Visual Studio 2015 on Windows but can be deployed cross platform on Windows and Linux.

Create folder C:\DevkitExample. Create the following sub-folders: crt0, dev, lib, tmp. Note: all content now preferred to reside under content sub-folder beneath the main dev folder. All content also built using scripts.


Development
Launch Visual Studio 2015. File | New | Project... | Visual C++ | Win32 | Win32 Project

 Name:  Game
 Location:  C:\DevkitExample\dev
 Create directory for solution  UNCHECKED
OK

 Application type:  Console application
 Additional options:  Empty project CHECKED
Finish

Ensure Visual Studio 2015 is configured as per instructions here to automate build process from Ctrl+1 hot key. Create folders beneath dev for .vscode and devkit. Import all code from here including build the scripts.

main.c
#include "main.h"
void main( void )
{
  devkit_SMS_init();
  devkit_SMS_setSpritePaletteColor( 0, devkit_RGB( 3, 3, 3 ) );
  devkit_SMS_displayOn();
  for( ;; )
  {
    devkit_SMS_waitForVBlank();
  }
}

Graphics
Follow all instructions from the previous post to download and install BMP2Tile utility to convert graphics into Sega Master System format. Download new gfxcomp_stm.dll STM compressed format to output directory.

Splash
Here is an example of background tiles that will exhaust the full 256 x 192 resolution e.g. the Splash screen:

Follow the same settings as per here but this time use this script to automate the corresponding formatting:

build.bat
bmp2tile.exe raw/splash.bmp ^
  -savetiles "splash (tiles).psgcompr" -removedupes -nomirror -planar -tileoffset 128 ^
  -savetilemap "splash (tilemap).stmcompr" ^
  -savepalette "splash (palette).bin" ^
  -fullpalette -exit

 Tiles:  Remove duplicates  Checked
 Tiles:  Planar tile output  Checked
 Tilemap:  Use sprite palette  Unchecked
 Tilemap:  In front of sprites  Unchecked
 Palette:  Output hex (SMS)  Checked

Opaque
Candy Kid, which is a Pacman clone, uses opaque background tiles to obscure the main sprite as he goes thru the exits. This technique renders a white 16x16 tile but uses sprite palette bitwise OR with tile priority.

tile_manager.c
static void draw_tile_priority( unsigned char offset, unsigned char x, unsigned char y )
{
  unsigned int priority = devkit_TILE_PRIORITY() | devkit_TILE_USE_SPRITE_PALETTE();

  devkit_SMS_setNextTileatXY( x + 0, y + 0 );
  devkit_SMS_setTile( ( *game_tiles__tilemap__bin + offset + 0 ) | priority );
}

IMPORTANT: the sprite palette color in this example must be black to match background despite white tiles.

Tools
In previous years, Gimp was used to convert graphics as Indexed [16] mode to meet the 4bpp Sega Master System compatible requirements. However, paint.net is great to output PNG files for BMP online converter:
 Color:  4 (indexed)
 With rows direction:  Bottom - Top (default)
 Quantization equal to:  8
 Using dithering:  No


Scrolling
Scrolling in video games involves moving graphics across a display, either horizontally and/or vertically such that the layout does not change but rather moves the view across as an image larger than the whole screen.

Horizontal scrolling was very popular for action, run-and-gun and shoot/beat 'em up games whereas vertical scrolling was used in top down shooters. The devkitSMS tutorial has both vertical and horizontal examples:

Horizontal
Here is the devkitSMS tutorial horizontal scrolling "Ice Hockey" example using the SMS_loadTileMap() API.


scroll_manager.c
void engine_scroll_manager_update_right( unsigned char delta )
{
  unsigned char *src = NULL;
  unsigned char ytile = 0;
  unsigned int index = 0;
  const unsigned int size = 2;

  unsigned int x = 0;
  unsigned char y = 0;

  if( scrollRightDivided8 < scrollWidth )
  {
    scroll -= delta;
    scrollRight += delta;
    scrollRightDivided8 = scrollRight / 8;
    devkit_SMS_setBGScrollX( scroll );

    if( ( scrollRight % 8 ) == delta )
    {
      for( ytile = 1; ytile < Y_TILE_MAX; ytile++ )
      {
        x = X_TILE_MAX + scrollRightDivided8;
        y = ytile - 1;
        index = ( ( BG_TILE_WIDTH*ytile ) + ( X_TILE_MAX + scrollRightDivided8 ) ) * 2;
        src = ( void * ) &hockey__tilemap__bin[ index ];
        devkit_SMS_loadTileMap( x, y, src, size );
      }
    }
  }
}

Vertical
Here is the devkitSMS tutorial vertical scrolling "Marilyn" [MM] example using the SMS_loadTileMap() API.


scroll_manager.c
void engine_scroll_manager_down()
{
  struct_scroll_object *so = &global_scroll_object;
  unsigned int index;
  unsigned int y;

  if( so->scroll < so->height )
  {
    so->scroll++;
    devkit_SMS_setBGScrollY( so->scroll );

    if( ( so->scroll % 8 ) == 0 )
    {
      y = ( 24 + ( so->scroll / 8 ) ) % 28;
      index = ( 24 + ( so->scroll / 8 ) ) * 32 * 2;
      devkit_SMS_loadTileMap( 0, y, ( void * ) &MM__tilemap__bin[ index ], so->size );
    }
  }
}

Vertical II
Here is another vertical scrolling example which prefers SMS_setNextTileatXY() after loading all the tiles.


map_manager.c
static void draw_map_row()
{
  struct_map_object *map_data = &global_map_object;
  unsigned char i, j;
  unsigned char y;
  unsigned char *map_char;
  unsigned int base_tile, tile;
  unsigned char buffer[ 16 ];

  decompress_map_row( buffer );
  for( i = 2, y = map_data->background_y, base_tile = 256; i; i--, y++, base_tile++ )
  {
    devkit_SMS_setNextTileatXY( 0, y );
    for( j = 16, map_char = buffer; j; j--, map_char++ )
    {
      tile = base_tile + ( *map_char << 2 );
      devkit_SMS_setTile( tile );
      devkit_SMS_setTile( tile + 2 );
    }
  }
}

PCM Samples
The Sega Master System is able to play high quality Pulse-Code Modulation [PCM] samples with the pcmenc tool built by Maxim from the SMS Power! community which means WAV files can be converted and played.

Single Bank
Ensure the pcmenc executable currently lives in ~/SDCC/bin folder and accessible from $PATH. Launch the terminal and execute the following command to convert an input "test" WAV file to pcmenc compatible file:
 if exist "SoundFx.wav" pcmenc -rto 1 -dt1 12 -dt2 12 -dt3 423 SoundFx.wav

This assumes that the converted WAV file will be less than 16KB; the maximum size for Sega Master System bank. If not then the WAV file will need to be converted to multiple WAV files + converted [example below].

Here is an example of converting an input WAV file using pcmenc to be SMS compatible for code integration.
Contains the engine code to init and play the converted WAV file as PCM sample on the Sega Master System.

sample_manager.c
void engine_sample_manager_init( const void *psginit );
void engine_sample_manager_play( const void *sample );

riff_manager.c
Public API that game code will call as wrapper around the sample manager to actually play the PCM sample.

IMPORTANT:
I've found that is usually safest to init the riff manager before playing each riff to avoid unwanted noise!

Multiple Banks
When the converted WAV file is greater than 16KB then use Audacity to convert the riff to multiple WAV files. Download, install and launch Audacity. Open WAV file. Divide into multiple smaller files using these settings:

 Project Rate (Hz)  44100
 Snap To  Off
 Selection Start  000,000,000 samples
 Length CHECKED  000,050,000 samples
 Audio Position  000,000,000 samples

Hit Ctrl+B | Enter "01". Repeat as per number of banks required at 50,000 samples intervals for example:
 Riff 01  Selection Start  000,000,000 samples  Length CHECKED  000,050,000 samples
 Riff 02  Selection Start  000,050,000 samples  Length CHECKED  000,050,000 samples
 Riff 03  Selection Start  000,100,000 samples  Length CHECKED  000,050,000 samples
 Riff 04  Selection Start  000,150,000 samples  Length CHECKED  000,050,000 samples

File menu | Export Multiple. Choose export location | Export | OK. Execute the following script to convert:
if exist "01.wav" pcmenc -rto 1 -dt1 12 -dt2 12 -dt3 423 01.wav
if exist "02.wav" pcmenc -rto 1 -dt1 12 -dt2 12 -dt3 423 02.wav
if exist "03.wav" pcmenc -rto 1 -dt1 12 -dt2 12 -dt3 423 03.wav
if exist "04.wav" pcmenc -rto 1 -dt1 12 -dt2 12 -dt3 423 04.wav

Finally, rename the *.wav.pcmenc files to more code friendly names and copy the files to parent banks folder with each *.wav.pcmenc file in its own bank. Use this utiltiy to automate this task and generate the scripts.

Invoke the riff manager similar to single bank example except iterate thru all banks that are required to play riff. The only current drawback with this technique is the main thread blocks as the riff plays synchronously!


Banked Code
SDCC 4.x supports banked code which means it is now possible to page in and out code in a transparent manner. The banked code should be written in separate source files that get allocated in separate code banks. To summarize, banked code means that total code will not be restricted to 32KB maximum size.


Method
1. Put all banked code in separate source files marking banked functions using __banked SDCC keyword.
 banked_code_1.h  banked_code_1.c
 #ifndef _BANK_1_H_
 #define _BANK_1_H_

 int banked_code_1() __banked;

 #endif//_BANK_1_H_
 #include "banked_code_1.h"

 int banked_code_1() __banked
 {
 	return 1;
 }

2. Compile each banked code source file into a specific separate code segment as part of the build script.
 sdcc --debug -c -mz80 --codeseg BANK1 banked_code_1.c
 sdcc --debug -c -mz80 --codeseg BANK2 banked_code_2.c
 sdcc --debug -c -mz80 --codeseg BANK3 banked_code_3.c

3. Use the newly provided crt0b_sms.rel as the first module into your linker call instead of crt0_sms.rel.
4. Instruct the linker to place the banked code at address 0x4000 + the virtual address of the bank which will be calculated as bank number * 2^16 i.e. code segment BANK1 at 0x14000, BANK2 at 0x24000 etc.
 sdcc --debug -o output.ihx -mz80 --no-std-crt0 --data-loc 0xC000 \
 -Wl-b_BANK1=0x14000 \
 -Wl-b_BANK2=0x24000 \
 -Wl-b_BANK3=0x34000 \
 ../crt0/crt0b_sms.rel \
 ../lib/SMSlib.lib \
 main.rel \
 banks/banked_code_1.rel \
 banks/banked_code_2.rel \
 banks/banked_code_3.rel \

5. Finally use the new makesms tool to convert the ihx output to sms format instead of the ihx2sms tool.
 makesms output.ihx output.sms


Summary
Armed with all this knowledge, we are now in an excellent position to upgrade any existing game projects for Sega Master System to latest version of devkitSMS on SDCC 4.x built cross platform for Windows and Linux!

Saturday, June 4, 2022

devkitSMS Programming Setup II

In 2017, we checked out devkitSMS Programming Setup to build 8-bit video games in C for the Sega Master System (SMS). Here we use SDCC v3.6.9 which allows maximum 32KB for your main ROM game code size.

Now, the latest devkitSMS requires SDCC 4.x which supports banked code which means it is now possible to page code out transparently. Plus we'd also like to build SMS projects cross platform for Windows and Linux.


Let’s check it out!

devkitSMS
The devkitSMS is a collection of tools and code built specifically for the Sega Master System but also supports homebrew development using C language for SG-1000, SC-3000 and the Sega Game Gear.

Software
Follow all instructions from the previous post: this documents how to setup the pre-requisite software.

Here is a summary of all required software to be installed:
 Name Version
 C IDE Editor Visual Studio 2015
 C IDE Editor Visual Studio Code
 Cross compiler Small Device C Compiler
 
 Name Version
 Make files Cygwin
 Emulators Emulicious, Fusion, Meka
 Debugger Emulicious Debugger
Note: Emulicioushas dependency on Java therefore launch using java -jar ~/Sega/Emulicious/Emulicious.jar

Windows
Download and install sdcc-4.1.0-x64-setup.exe to C:\Program Files\SDCC. Choose all features to install.


There should be no extra configuration except add C:\Program Files\SDCC\bin to the Environment PATH.


Start | Run | cmd. Type sdcc --version. The following info should display to confirm SDCC version 4.1.0:


Linux
Download and extract sdcc-4.1.0-amd64-unknown-linux2.5.tar.bz2 to ~/sdcc. This should install all features.


There should be no extra configuration except add $HOME/sdcc/bin to the ~/.bashrc file so always available.
 gedit ~/.bashrc
 export PATH="$PATH:$HOME/sdcc/bin"

Launch Terminal. Type sdcc --version [sdcc -v]. The following should display to confirm SDCC version 4.1.0:


Directories
 Windows  C:\Program Files\SDCC\bin
 Linux  ~/sdcc/bin

devkitSMS
Navigate to the devkitSMS repository on github. @sverx has full instructions here and advises to copy the following 4x executables into SDCC bin folder: assets2banks.exe, folder2c.exe, ihx2sms.exe, makesms.exe.
# Clone devkitSMS
git clone https://github.com/sverx/devkitSMS.git

# Copy 4x files
cd devkitSMS
copy assets2banks/%PLATFORM%/assets2banks %INSTALLATION%/SDCC/bin
copy folder2c/%PLATFORM%/folder2c.exe %INSTALLATION%/SDCC/bin
copy ihx2sms/%PLATFORM%/ihx2sms.exe %INSTALLATION%/SDCC/bin
copy makesms/%PLATFORM%/makesms.exe %INSTALLATION%/SDCC/bin

Note: my preference is to usually copy the relevant files up-to-date as each Master System project is built.

Example
As an example, replicate the simple program from 2017 that sets the border colors of the screen using devkitSMS but this time we will port the Windows build cross platform to Linux and include debugging!

Create new directory HelloWorld: ~/HelloWorld. Copy these files across crt0_sms.rel, SMSlib.h, SMSlib.lib. Launch Visual Studio Code. Open HelloWorld directory. Create new file main.c and enter the following code:

main.c
#include "SMSlib.h"
void main ( void )
{
  SMS_setSpritePaletteColor( 0, RGB( 3, 3, 3 ) );
  SMS_displayOn();
  for ( ;; )
  {
    SMS_waitForVBlank();
  }
}

SMS_EMBED_SEGA_ROM_HEADER(9999, 0);
SMS_EMBED_SDSC_HEADER(1, 0, 2017, 9, 15, "StevePro Studios", "Hello World", "Simple Sega Master System demo to run on real hardware!");

Build
Manually compile, link and execute the Hello program. Launch command prompt: Start | Run | cmd.


Change directory cd ~/HelloWorld. Next, execute following 3x commands (in bold) but add debug keyword:
 ACTION  COMMAND  OUTPUT
 Compile   sdcc --debug -c -mz80 main.c  main.rel
 Link  sdcc --debug -o output.ihx -mz80 --data-loc 0xC000 --no-std-crt0 crt0_sms.rel
 main.rel SMSlib.lib
 output.ihx
 Exceute  ihx2sms output.ihx output.sms  output.sms 

Finally, type java -jar ~/Sega/Emulicious/Emulicious.jar output.sms to launch the Hello program.
Congratulations! You have just written your first SMS program using devkitSMS.


Automate
Let's automate the build process: create build script file that contains the previous commands. On Windows name the file build.bat. On Linux name the file build.sh and add EXE permissions as chmod +x build.sh.
@echo off
sdcc --debug -c -mz80 main.c
sdcc --debug -o output.ihx -mz80 --data-loc 0xC000 --no-std-crt0 crt0_sms.rel main.rel SMSlib.lib
ihx2sms output.ihx output.sms
java -jar ~/Sega/Emulicious/Emulicious.jar output.sms

Visual Studio Code
Finally, add hidden .vscode folder in Visual Studio Code + include tasks.json and launch.json files beneath:

tasks.json
{
    "version": "2.0.0",
    "label": "build",
    "type": "shell",
    "linux": {
        "command": "./build.sh"
    },
    "windows": {
        "command": "./build.bat"
      },
    "presentation": {"echo": true, "reveal": "always", "focus": false, "panel": "shared", "showReuseMessage": false, "clear": true},
    "group": {"kind": "build", "isDefault": true},
}
Important: On Windows prefer the ./build syntax as Linux otherwise an "unrecognized cmdlet" may result.

launch.json
{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "emulicious-debugger",
            "request": "launch",
            "name": "Launch in Emulicious",
            "program": "${workspaceFolder}/output.sms",
            "port": 58870,
            "stopOnEntry": true
        }
    ]
}
On Linux, launch Emulicious as above. Press Ctrl + Shift + B to build code and F5 to debug step thru code:


Visual Studio 2015
For completeness, if the main workstation is Windows then another option is Visual Studio 2015 can also be used to debug step thru the ANSI-C source code. For more background info see this. Here is the alternative:

main.c
#include "main.h"
void main( void )
{
  devkit_SMS_init();
  devkit_SMS_setSpritePaletteColor( 0, devkit_RGB( 3, 3, 3 ) );
  devkit_SMS_displayOn();
  for( ;; )
  {
    devkit_SMS_waitForVBlank();
  }
}

Summary
To summarize, the Sega Master System development process has been very consistent after the SDCC 4.x upgrade plus the ability to support banked code means initial 32KB ROM restriction now no longer applies!
This will be the topic of the next post.