-
Notifications
You must be signed in to change notification settings - Fork 8
3. "Hello World" Tutorial
This tutorial is actually a bit more than "just" the classical "Hello World". It contains five small sub-tutorials to get you started:
- Classical "Hello World" using the Welcome-Screen
- Add a new menu-item and show an "About & Help" menu
- Add a menu-item to flip the joystick ports
- Add three menu items to change the color of the "ball"
- Understanding the QNICE debug console
[@lydon: Here we could advertize your YouTube video]
Please make sure that you have completed the 2. First Steps before
proceeding with the tutorials shown here. Use the MyFirstM2M clone you made
there for the following exercises.
By default, the Welcome-Screen is shown after power-on (and/or loading the
core, respectively) and after each reset. You can configure this behavior in
the file CORE/vhdl/config.vhd:
-- show the welcome screen in general
constant WELCOME_ACTIVE : boolean := true;
-- shall the welcome screen also be shown after the core is reset?
-- (only relevant if WELCOME_ACTIVE is true)
constant WELCOME_AT_RESET : boolean := true;
For now, do not change anything here, yet, because we want to use the Welcome-Screen to show our "Hello World" message.
Search for the constant SCR_WELCOME in config.vhd. You will notice that
this is quite a long, multi-line string constant. You will recognize the
contents of the Welcome-Screen that the demo-core is showing. Please be
aware that you can and need to use \n to add newlines so that you can format
your welcome screen.
Go to the lines that contains this segment:
"\n\nEdit config.vhd to modify welcome screen.\n\n" &
"You can for example show the keyboard map.\n" &
"Look at this example from Game Boy Color:\n\n\n" &Replace the segment with your personal "Hello World!" message for example:
"\n\nHello World! Hello M2M! Hello MEGA65!\n\n\n\n" &Generate a bitstream and run the core.
After that, you might want to set the above-mentioned flags to false so that
the Welcome-Screen disappears completely: It will neither be shown upon the
initial startup of the core then nor will it be shown after a reset.
This mini-tutorial catches two birds with one stone:
- You'll get a first sense for how the on-screen-menu works
- You'll understand the help-system
M2M contains a help-system that allows you to have up to 15 help topics, where each help topic can have 256 screens. Let's add a menu item that shows some demo help content.
Search for the constant OPTM_SIZE in config.vhd and change its value
from 25 to 27.
Add this to the string constant OPTM_ITEMS before the "Close Menu" item:
" About & Help\n" &
"\n" &The string constant should now look like this:
constant OPTM_ITEMS : string :=
" Demo Headline A\n" &
"\n" &
" Item A.1\n" &
" Item A.2\n" &
" Item A.3\n" &
" Item A.4\n" &
"\n" &
" HDMI Frequency\n" &
"\n" &
" 50 Hz\n" &
" 60 Hz\n" &
"\n" &
" Drives\n" &
"\n" &
" Drive X:%s\n" &
" Drive Y:%s\n" &
" Drive Z:%s\n" &
"\n" &
" Another Headline\n" &
"\n" &
" HDMI: CRT emulation\n" &
" HDMI: Zoom-in\n" &
" Audio improvements\n" &
"\n" &
" About & Help\n" &
"\n" &
" Close Menu\n";Now go to this block of constants:
constant OPTM_G_Demo_A : integer := 1;
constant OPTM_G_HDMI : integer := 2;
constant OPTM_G_Drive_X : integer := 3;
constant OPTM_G_Drive_Y : integer := 4;
constant OPTM_G_Drive_Z : integer := 5;
constant OPTM_G_CRT : integer := 6;
constant OPTM_G_Zoom : integer := 7;
constant OPTM_G_Audio : integer := 8;And add one more:
constant OPTM_G_AboutHelp : integer := 9;After that, locate the constant OPTM_GROUPS and add two more line items
right before this block:
OPTM_G_LINE, -- Line
OPTM_G_CLOSE -- Close Menu
);The line items that you should add are these:
OPTM_G_LINE, -- Line that separates the Help menu
OPTM_G_AboutHelp + OPTM_G_HELP, -- Show help topic #1 As a result, OPTM_GROUPS will look like this:
constant OPTM_GROUPS : OPTM_GTYPE := ( OPTM_G_TEXT + OPTM_G_HEADLINE, -- Headline "Demo Headline"
OPTM_G_LINE, -- Line
OPTM_G_Demo_A + OPTM_G_START, -- Item A.1, cursor start position
OPTM_G_Demo_A + OPTM_G_STDSEL, -- Item A.2, selected by default
OPTM_G_DEMO_A, -- Item A.3
OPTM_G_DEMO_A, -- Item A.4
OPTM_G_LINE, -- Line
OPTM_G_TEXT, -- Headline "HDMI Frequency"
OPTM_G_LINE, -- Line
OPTM_G_HDMI + OPTM_G_STDSEL, -- 50 Hz, selected by default
OPTM_G_HDMI, -- 60 Hz
OPTM_G_LINE, -- Line
OPTM_G_TEXT, -- Headline "Drives"
OPTM_G_LINE, -- Line
OPTM_G_Drive_X + OPTM_G_MOUNT_DRV, -- Drive X
OPTM_G_Drive_Y + OPTM_G_MOUNT_DRV, -- Drive Y
OPTM_G_Drive_Z + OPTM_G_MOUNT_DRV, -- Drive Z
OPTM_G_LINE, -- Line
OPTM_G_TEXT, -- Headline "Another Headline"
OPTM_G_LINE, -- Line
OPTM_G_CRT + OPTM_G_SINGLESEL, -- On/Off toggle ("Single Select")
OPTM_G_Zoom + OPTM_G_SINGLESEL, -- On/Off toggle ("Single Select")
OPTM_G_Audio + OPTM_G_SINGLESEL, -- On/Off toggle ("Single Select")
OPTM_G_LINE, -- Line that separates the Help menu
OPTM_G_AboutHelp + OPTM_G_HELP, -- Show help topic #1
OPTM_G_LINE, -- Line
OPTM_G_CLOSE -- Close Menu
);Please note that the items in OPTM_GROUPS are having a 1-to-1 relationship
to each line (separated by \n) in OPTM_ITEMS. Also please note that
OPTM_ITEMS now has 27 lines and OPTM_GROUPS has 27 array elements,
just as specified by OPTM_SIZE.
That's it! You now have an "About & Help" menu item that opens demo content that is three screens long.
Try it: Generate a bitstream and play with it. You can open the "About & Help" menu using Return and you can browse through the multiple help pages using Cursor Left and Cursor Right. Press Space to close the help menu.
You will find a more in-depth description of how the Shell's menu system works here @TODO and all details about the help-system here @TODO. Nevertheless, here is the condensed overview:
-
OPTM_ITEMSdefines the names of the menu items andOPTM_GROUPSdefines the properties and behaviour of the menu items. There is a 1-to-1 relationship between both: A line inOPTM_ITEMScorresponds to an array element inOPTM_GROUPS. - Empty lines in
OPTM_ITEMScan be shown as lines, when the corresponding entry inOPTM_GROUPSis set toOPTM_G_LINE. - Each menu item that is supposed to "do something" needs to be part of a
"Menu Group". This is why you defined the constant
OPTM_G_AboutHelpwhile following the recipe above. - Multi-select menu items need all to be in the same Menu Group. See how all
the "Item A.*" menu items are part of
OPTM_G_Demo_A. - Single-select menu items - such as the help menu item - need to have a
unique identifier ("Group"). This is why you gave your constant
OPTM_G_AboutHelpthe unique value9. - Attributes and properties can be added to Menu Groups using the
+operator because the values are arranged in a way that the Shell can recognize single bits. This is why you added theOPTM_G_HELPattribute to theOPTM_G_AboutHelpmenu item identifier. - The help system counts: The first menu item that has a
OPTM_G_HELPattribute will show the first help topic. The second menu item that has aOPTM_G_HELPattribute will show the second help topic, and so on. The various help menu items do not need to be in proximity. - The example
config.vhdfile provided with M2M contains a three-page (three-screen) demo help topic. This tutorial does not explain more details how the help-system itself works, but you can look at the constantsWHS_DATAandWHSto get a first overview or go to the reference page @TODO to learn more.
@TODO @TODO @TODO
@TODO @TODO @TODO
@TODO @TODO @TODO
@TODO @TODO @TODO
@TODO @TODO @TODO
@TODO @TODO @TODO