Mercurial > sos > sos

annotate README @ 150:e72f984619c7

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Consolidated a lot of the defines which relate to the memory layout There is a new file (include/os/memLayout.h) which now includes just about all the #defines
author Jonathan Pevarnek <pevarnj@gmail.com>
date Wed, 02 Nov 2011 09:55:09 -0400
parents 175279b7d3d7
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
0
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
1 This README will help you figure out what this minimal system does. In
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
2 short, it doesn't do a whole lot. Making it do something useful is up to
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
3 you.
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
4
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
5 You can safely ignore:
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
6 ipl/*
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
7 scripts/*
82
175279b7d3d7 updated the readme
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents: 0
diff changeset
8 arch/*
0
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
9
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
10 You can put your code in src/ and your include files in include/. If you
82
175279b7d3d7 updated the readme
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents: 0
diff changeset
11 add any .c files, you'll have to add them to the foo_OBJS line in the
175279b7d3d7 updated the readme
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents: 0
diff changeset
12 Makefile.
0
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
13
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
14 Building
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
15 --------
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
16
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
17 First, you should make sure that the cross building tools are in your path.
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
18 For example, my system has /opt/cross/bin in $PATH.
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
19
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
20 In the top level directory, you simply run `make'.
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
21
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
22 Running
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
23 -------
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
24
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
25 Go into the hercules directory, and run:
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
26
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
27 $ hercules -f herc.cnf
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
28
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
29 Then, in another terminal, run:
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
30
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
31 $ telnet 127.0.0.1 3270
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
32
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
33 Hercules is the emulator for the system that you are developing for (x86 is
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
34 awful to develop for in a stand-alone way).
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
35
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
36 Now, in the Hercules window, you can type:
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
37
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
38 ==> ipl c
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
39
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
40 That tells it to start executing whatever program is on device 0x000c. This
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
41 happens to be whatever got compiled before. (IPL stands for Initial Program
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
42 Load.) Once you tell the emulator to run your code, you can interact with
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
43 your code in the telnet session.
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
44
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
45 If at any point you see a message in the Hercules window about the
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
46 processor stopping due to a SIGP or a "disabled wait state" you have a bug
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
47 in your code.
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
48
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
49 The Internals
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
50 -------------
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
51
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
52 After the init code runs, it calls the start function in src/init.c. It
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
53 takes one argument, which specifies the amount of memory you have. If, for
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
54 example, it it given 1048576, you know that addresses 0...1048575 are valid.
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
55 Note that unlike the standard C/C++ application environment, you can
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
56 load from/store to any of those addresses. Accessing a NULL pointer will
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
57 NOT result in a SIGSEGV or a similar death of the program. There are a few
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
58 ranges of memory that you should know about.
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
59
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
60 0... 8191 hw state area (the hw stores status info here, do not touch)
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
61 8192...
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
62 ...1048575 the stack
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
63 1048576... the code & globals
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
64
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
65 In English, the first 8k is used by the hardware to store important state.
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
66 You will not need to read/modify this state. The code starts at 1MB, and
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
67 takes up whatever amount of space is necessary for it. The stack starts at
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
68 1MB and grows downward. You can do whatever you want with the unused
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
69 memory. (My suggestion is to assume that the code + globals will not take
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
70 more than say 512kB, the stack no more than 512kB, and then think of the
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
71 layout as:
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
72
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
73 0k... 8k hw state
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
74 8k...512k free
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
75 512k... 1M stack
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
76 1M...1.5M code + globals
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
77 1.5M... free
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
78
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
79 That's my suggestion. It's not the only way to do this, but it's simple to
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
80 think about.)
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
81
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
82 There are 2 more functions that you are provided:
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
83
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
84 int putline(char *buf, int len)
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
85 prints len characters pointed to by buf; it returns -1 if the
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
86 length is invalid, or the length once the I/O completes
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
87
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
88
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
89 int getline(char *buf, int len)
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
90 reads a line of text and saves up to len characters at buf; it
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
91 returns -1 if the length is invalid, or the number of bytes put into
5d9f272f4db6 import template
Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
parents:
diff changeset
92 buf