Skip to content

Commit 67ae94b

Browse files
YuguoWHYuguoWH
committed
DOC: add makefile manual, add iotdk pin_mux
Signed-off-by: Yuguo Zou <[email protected]>
1 parent b2ccf68 commit 67ae94b

File tree

3 files changed

+191
-7
lines changed

3 files changed

+191
-7
lines changed

‎doc/documents/getting_started/getting_started.rst‎

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -72,7 +72,7 @@ Follow these steps to build a sample application
7272
7373
make TOOLCHAIN=gnu BOARD=emsk BD_VER=23 CUR_CORE=arcem11d
7474
75-
.. note:: **make** for ARC GNU toolchain, **gmake** for MetaWare toolkit
75+
.. note:: **make** for ARC GNU toolchain, **gmake** for MetaWare toolkit. For more details of commands, see :ref:`makefile_manual`
7676

7777
Hardware Preparation
7878
####################
@@ -92,11 +92,6 @@ See the following procedures to check peripherals and board settings. The periph
9292
:maxdepth: 1
9393

9494
hardware_requirement.rst
95-
96-
97-
.. toctree::
98-
:maxdepth: 1
99-
10095
peripheral_preparation.rst
10196

10297
Running a Sample Application
@@ -117,6 +112,13 @@ Follow these steps to run the sample application.
117112
118113
.. note:: No peripheral modules are required to run the ``blinky`` example.
119114

115+
See the following manual for information on make/gmake command and embARC makefile system.
116+
117+
.. toctree::
118+
:maxdepth: 1
119+
120+
makefile_manual.rst
121+
120122

121123
Advanced Topics
122124
###############

‎doc/documents/getting_started/makefile_manual.rst‎

Lines changed: 175 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,175 @@
1+
.. _makefile_manual:
2+
3+
Makefile Manual
4+
===============
5+
6+
This is an introduction to embARC makefile system, which including a set of tools that you could build, run and debug your code with.
7+
This document also contains a quick manual helping you to find the right command for your project.
8+
9+
Here are quick in-page links of some mostly used commands:
10+
11+
* help_
12+
* cfg_
13+
* build_
14+
* gui_
15+
* run_
16+
* distclean_
17+
18+
Commands Details
19+
################
20+
21+
This make system is based on make/gmake. Please make sure your environment meets the :ref:`software_requirement`.
22+
23+
.. _help:
24+
25+
help
26+
****
27+
This is one of the most useful commands, you could use it whenever you have problem finding the right command.
28+
Help information will be printed to your console.
29+
30+
.. code-block:: console
31+
32+
make help
33+
34+
or:
35+
36+
.. code-block:: console
37+
38+
gmake help
39+
40+
In the following part of this manual, we will only use ``make`` in example, you could change it to ``gmake`` anytime.
41+
42+
.. note:: make/gmake is provided in the MetaWare toolkit (gmake) and ARC GNU toolchain (make).
43+
44+
Some text
45+
46+
.. _cfg:
47+
48+
cfg
49+
***
50+
51+
The basic way of this command is to enter ``make cfg``, the makefile system will check and print out current settings as well as supported configurations, showing below.
52+
53+
.. code-block:: console
54+
55+
make cfg
56+
"=======Current Configuration======="
57+
"Host OS : Windows"
58+
"Board : emsk"
59+
"Hardware Version : 22"
60+
"Core Configuration : arcem7d"
61+
"CPU Clock HZ : "
62+
"Peripheral Clock HZ: "
63+
"Build Toolchain : mw"
64+
"Optimization Level : O2"
65+
"Debug Jtag : usb"
66+
"======Supported Configurations of emsk-22======"
67+
"Boards (BOARD) : axs emsk hsdk iotdk nsim"
68+
"Core Configurations (CUR_CORE) : arcem11d arcem7d arcem9d"
69+
"Build Toolchains (TOOLCHAIN) : gnu mw"
70+
"Debug Jtags (JTAG) : usb opella"
71+
72+
At supported Configurations, you can find different choices for your command, the uppercase words in parentheses are paramater names to be used in your command.
73+
For example, the command below will execute your command for an *EMSK* board with *arcem7d* core, toolchain would be *gnu* and JTAG connection is via *USB*.
74+
75+
.. code-block:: console
76+
77+
make BOARD=emsk CUR_CORE=arcem7d TOOLCHAIN=gnu JTAG=usb [your command]
78+
79+
For the details of command parameters, see :ref:`Useful_Options`
80+
81+
A handy application to use ``cfg``:
82+
Suppose we need to build the project on hsdk, but we are not sure the exact core name.
83+
Then we could use cfg command with BOARD=hsdk so makefile system could find avaiable cores for us.
84+
In this case there are *archs38_c0 archs38_c1 archs38_c2 archs38_c3* available.
85+
86+
.. code-block:: console
87+
88+
make BOARD=hsdk cfg
89+
"=======Current Configuration======="
90+
"Host OS : Windows"
91+
"Board : hsdk"
92+
"Hardware Version : 10"
93+
"Core Configuration : archs38_c0"
94+
"CPU Clock HZ : "
95+
"Peripheral Clock HZ: "
96+
"Build Toolchain : mw"
97+
"Optimization Level : O2"
98+
"Debug Jtag : usb"
99+
"======Supported Configurations of hsdk-10======"
100+
"Boards (BOARD) : axs emsk hsdk iotdk nsim"
101+
"Core Configurations (CUR_CORE) : archs38_c0 archs38_c1 archs38_c2 archs38_c3"
102+
"Build Toolchains (TOOLCHAIN) : gnu mw"
103+
"Debug Jtags (JTAG) : usb opella"
104+
105+
106+
107+
.. _build:
108+
109+
build
110+
*****
111+
112+
This command will clean and build the project with selected paramaters.
113+
114+
Here is a example using EMSK (version 1.1, arcem6 core), compiled with gnu.
115+
116+
.. code-block:: console
117+
118+
make BOARD=emsk BD_VER=11 CUR_CORE=arcem6 TOOLCHAIN=gnu build
119+
120+
.. _gui:
121+
122+
gui
123+
***
124+
125+
Debug command, will first compile and link the project, then load the project with debugger and start debugging.
126+
127+
Here is a example using EMSK (version 2.2, arcem9d core), compiled with Metaware and debug via usb connection.
128+
129+
.. code-block:: console
130+
131+
make BOARD=emsk BD_VER=22 CUR_CORE=arcem9d TOOLCHAIN=mw JTAG=usb [your command]
132+
133+
.. _run:
134+
135+
run
136+
***
137+
138+
When this command is used, makefile system will first compile and link the project.
139+
Then it will try to download the project to the board and start running it. If no target board is found, it will return error.
140+
141+
Here is a example using IoTDK (version 1.0, arcem9d core), compiled with Metaware and debug via usb connection.
142+
143+
.. code-block:: console
144+
145+
make BOARD=iotdk BD_VER=10 CUR_CORE=arcem9d TOOLCHAIN=mw JTAG=usb run
146+
147+
You may also use it wiout BD_VER and CUR_CORE options since they are default options.
148+
149+
.. code-block:: console
150+
151+
make BOARD=iotdk TOOLCHAIN=mw JTAG=usb run
152+
153+
.. _distclean:
154+
155+
distclean
156+
*********
157+
158+
This command will clean the directory, removing all object files of all boards.
159+
160+
.. code-block:: console
161+
162+
make distclean
163+
164+
165+
.. _Useful_Options:
166+
167+
Useful Options
168+
##############
169+
170+
#. Boards (**BOARD**): Use this option to check config for different boards. Usually he default BOARD setting is EMSK.
171+
#. Core Configurations (**CUR_CORE**): shows available core choices.
172+
#. Build Toolchains (**TOOLCHAIN**):To choose from different toolchain.
173+
#. Debug Jtags (**JTAG**): In most case the micro-usb interface on board supports JTAG debugging. Ashling's Opella-XD-ARC is also support by some boards.
174+
#. Board version (**BD_VER**): Often used by EMSK which has many versions.
175+

‎doc/documents/getting_started/peripheral_preparation.rst‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ On most of embARC boards, pins are multiplexed for various usages: uart, i2c, sp
1111
We will take PMOD interface as example to explain the setting method. Other interfaces (Andruino, MikroBUS, etc.) can take PMOD as reference, and use the same method for setting.
1212

1313
1. You need to find mux controller code at ``embarc_osp/board/[board_type]/drivers/mux``.
14-
One exception is board `The ARC IoT Development Kit (IoTDK) <https://www.synopsys.com/dw/ipdir.php?ds=arc_iot_development_kit>`_ which has fixed pin assignment and does **NOT** have mux controller.
14+
[board_type] should be replaced to board type name, such as *emsk*, *hsdk* or *iotdk*.
1515

1616
2. If you are using EMSK, go to mux.c and find ``io_mux_init()`` function, you will see it calls ``set_pmod_mux()`` with MUX options as parameters.
1717
MUX options are defined in mux.h and you could change them as you see fit.
@@ -35,6 +35,13 @@ Now your code should be like this:
3535
3. If you are using HSDK, go to mux.c and find ``io_mux_init()`` function, you will find it calls ``creg_hsdc_set_gpio_mux()`` with paramater array ``gpio_mux_config`` as MUX options.
3636
By default all pins are set to GPIO, other MUX options are defined in ``PINMUX_TYPE`` in ``embarc_osp/device/inc/dev_pinmux.h``
3737

38+
4. If you are using IoTDK, go to mux.c and find ``int32_t io_pmod_config(uint32_t pmod, uint32_t type, uint32_t config)`` function.
39+
All three parameters should use definitions in ``embarc_osp/device/inc/dev_pinmux.h``.
40+
41+
* The first paramater can be choose from ``PMOD_PORT`` (e.g. *PMOD_A*, *PMOD_B*, *PMOD_C*), other inputs will be ignored.
42+
* The second parameter should be in ``PMOD_TYPE``, unsupported options will have no effect.
43+
* The third parameter should be ``IO_PINMUX_ENABLE`` or ``IO_PINMUX_DISABLE``, enabling or disabling the mux controller respectively.
44+
3845
.. note:: To learn what interface your board has, please go to :ref:`board_bsp`
3946

4047
PMOD Modules

0 commit comments

Comments
 (0)