Skip to content

Commit 186eb62

Browse files
anthony-kolesovanthony-kolesov
committed
Merge branch 'arc-dev' into arc-staging
2 parents 2ac851b + 1cabd5b commit 186eb62

File tree

125 files changed

+1745
-18
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

125 files changed

+1745
-18
lines changed

‎doc/baremetal/ashling-axs.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -121,6 +121,7 @@ To debug several cores on the AXC00x card simultaneously, start
121121
additional GDBs and connect to the required TCP ports. Cores are controlled
122122
independently from each other.
123123

124+
.. _known-issues:
124125

125126
Known issues
126127
------------

‎doc/baremetal/openocd-axs.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -88,6 +88,8 @@ For example to build an application for AXS103/HS36::
8888
+-----+--------+---------------------------------------------------------+
8989

9090

91+
.. _openocd-axs-board-configuration:
92+
9193
Board configuration
9294
-------------------
9395

‎doc/conf.py‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -214,10 +214,12 @@
214214
#'pointsize': '10pt',
215215

216216
# Additional stuff for the LaTeX preamble.
217-
#'preamble': '',
217+
# Increase limitations on the number of floats.
218+
'preamble': '\usepackage{morefloats}',
219+
'preamble': '\usepackage{float}',
218220

219221
# Latex figure (float) alignment
220-
#'figure_align': 'htbp',
222+
'figure_align': 'H',
221223
}
222224

223225
# Grouping the document tree into LaTeX files. List of tuples

‎doc/ide/arc-project-templates.rst‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
.. _arc-project-templates:
2+
3+
ARC Project Templates
4+
=====================
5+
6+
There are several ARC projects types available in the C project dialog:
7+
**ARC Cross ELF32 Target Application**, **ARC Cross ELF32 Target Static
8+
Library**, **AXS10x Projects**, **EM Starter Kit Projects**.
9+
10+
.. note::
11+
Note: for each of these project types there is a list of toolchains which
12+
are supported by it.
13+
14+
* **ARC Cross ELF32 Target Application** and **ARC Cross ELF32 Target Static
15+
Library** support all of the toolchains,
16+
* **AXS101 Projects** supports ARC 600, ARC 700 and ARC EM toolchains,
17+
* **AXS102 Projects** and **AXS 103 Projects** support only ARC HS toolchain,
18+
* **EM Starter Kit Projects** -- only ARC EM toolchain.
19+
20+
Project types are only available in the project creation dialog if at least one
21+
of the corresponding toolchain compilers is found in the `PATH` environment
22+
variable or in `../bin/` directory relative to Eclipse executable.
23+
Then you choose a project template, list of available toolchains appears on the
24+
right side of the dialog. There are only toolchains that are supported by this
25+
type of project and also found in the `PATH` or `../bin/` directory.
26+
27+
.. figure:: images/creating_project/toolchains_list.png
28+
29+
List of available toolchains for a template
30+
31+
If you want to create an application for nSIM, choose **ARC Cross ELF32 Target
32+
Application**. There you can choose either an empty or "Hello World" project
33+
template. Please note that this "Hello World" project calls ``printf()`` function,
34+
so it can not be used on hardware development systems, since they use UART for
35+
input/output and libc library does not provide bindings between UART and
36+
C standard library I/O functions. For nSIM this project will work fine, but for
37+
hardware development systems please choose "Hello World" projects that use UART.
38+
On the contrary, "Hello World" projects under **EM Starter Kit Projects** project
39+
type use UART, so they are not suitable for nSIM.
40+
41+
If you want to create a project for a hardware development system, choose one of
42+
**AXS10x Projects** or **EM Starter Kit Projects**. For each of these project
43+
types there is an **Empty Project** in the list of templates and also **Empty
44+
Project For** templates. If you want to create an empty project for your board,
45+
choose an empty project template that is specific for your board and core you
46+
are using. These templates contain memory maps of the cores, which are then
47+
passed to linker. As for **Empty Project** templates, they are generated
48+
automatically by Eclipse and do not contain any specific information, so you
49+
would have to provide a memory map yourself, or your application might not work
50+
properly.
51+
52+
.. figure:: images/creating_project/memory_map.png
53+
54+
Memory map for **Hello World for EM SK 2.1 Project**
55+
56+
57+

‎doc/ide/building-linux-uclibc-applications.rst‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
Building Linux uClibc applications
2+
==================================
3+
4+
The C Project dialog has five ARC project types on Linux: ARC Cross ELF32
5+
Target Application, ARC Cross ELF32 Target Static Library, ARC Cross uClibc
6+
Target Application, ARC Cross uClibc Target Shared Library and ARC Cross uClibc
7+
Target Static Library.
8+
9+
10+
Creating a New C Project
11+
------------------------
12+
13+
1. Select File >New >C Project
14+
15+
.. figure:: images/uclibc/c_project_types_linux.png
16+
17+
C Project Types on Linux
18+
19+
20+
Choosing toolchain
21+
------------------
22+
23+
1. Choose proper toolchain for uClibc project type.
24+
25+
.. figure:: images/uclibc/uclibc_toolchain.png
26+
27+
uClibc supported toolchain
28+
29+
30+
Setting compile options based on CPU core
31+
-----------------------------------------
32+
33+
User should choose a proper toolchain for a core, for different core supports different compile options.
34+
35+
Compiling a uClibc application
36+
------------------------------
37+
38+
1. Select File >New >C Project
39+
40+
.. figure:: images/uclibc/hello_uclibc_application.png
41+
42+
Hello_uClibc_Application
43+
44+
2. Getting compiling output in console
45+
46+
.. figure:: images/uclibc/hello_uclibc_application_700_output.png
47+
48+
Hello_uClibc_Application_700_output
49+
50+
Compiling a uClibc Static Library
51+
---------------------------------
52+
53+
1. Select File >New >C Project
54+
55+
.. figure:: images/uclibc/hello_uclibc_staticlib.png
56+
57+
Hello_uClibc_Staticlib
58+
59+
2. Getting compiling output in console
60+
61+
.. figure:: images/uclibc/hello_uclibc_staticlib_700_output.png
62+
63+
Hello_uClibc_Staticlib_700_output
64+
65+
Compiling a uClibc Shared Library
66+
---------------------------------
67+
68+
1. Select File >New >C Project
69+
70+
.. figure:: images/uclibc/hello_uclibc_sharedlib.png
71+
72+
Hello_uClibc_Sharedlib
73+
74+
2. Getting compiling output in console
75+
76+
.. figure:: images/uclibc/hello_uclibc_sharedlib_700_output.png
77+
78+
Hello_uClibc_Sharedlib_700_output

‎doc/ide/building-user-guide.rst‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
.. _building-user-guide:
2+
3+
Building User Guide
4+
===================
5+
6+
Project Build Settings
7+
----------------------
8+
9+
To see your project build settings, right click on your project and select
10+
**Properties** from the pop-up menu. In the appeared dialog choose
11+
**C/C++ Build > Settings**, then select **Tool Settings** tab.
12+
13+
.. figure:: images/building/properties.png
14+
15+
Project Build Settings page
16+
17+
At the left of the tab there is a list of tools which are used to build your
18+
project and **Target Processor**, **Debugging** and **Additional Tools** pages.
19+
For each of the listed tools there are some pages where you can set properties
20+
for these tools.
21+
22+
Target Processor Page
23+
---------------------
24+
25+
On this page there are properties that describe your target. These properties
26+
are different for different processors.
27+
28+
.. figure:: images/building/hs_target_options.png
29+
30+
Target Processor Page for ARC HS
31+
32+
CPU option
33+
----------
34+
35+
CPU option for ARC 600 and ARC 700 has only one value, but for ARC EM there
36+
are several possible values: ``arcem``, ``em``, ``em4``, ``em4_dmips``, ``em4_fpus``
37+
and ``em4_fpuda``. Possible values for ARC HS CPU are ``archs``, ``hs``, ``hs34``,
38+
``hs38`` and ``hs38_linux``. For each of these values there are precompiled standard
39+
libraries that use some other target options. For example, if you choose ``hs34``
40+
as you CPU, standard library that uses atomic functions and multiply
41+
option "mpy" will be used. Values of these options are set in IDE when CPU is
42+
selected and can not be changed to weaker values without changing CPU. For
43+
example, if DP FPU is selected as a result of selecting CPU, you can not change
44+
it to any of SP FPU values or "None", but you can change it to DP FPU with extensions.
45+
46+
.. figure:: images/building/hs34_selected.png
47+
48+
ARC HS Target Processor Page with ``hs34`` selected as CPU value
49+
50+
Here are the options that are required for each of CPU values:
51+
52+
.. table::
53+
54+
========= ======== ====================== ============== ============ ============== ======= ====
55+
CPU Multiply FPU Barrel shifter Code density Integer divide Bitscan Swap
56+
========= ======== ====================== ============== ============ ============== ======= ====
57+
arcem wlh1 none \+ \+ \- \- \-
58+
em none none \- \- \- \- \-
59+
em4 none none \- \+ \- \- \-
60+
em4_dmips wlh1 none \+ \+ \+ \+ \+
61+
em4_fpus wlh1 SP FPU \+ \+ \+ \+ \+
62+
em4_fpuda wlh1 FPU with double assist \+ \+ \+ \+ \+
63+
========= ======== ====================== ============== ============ ============== ======= ====
64+
65+
.. table::
66+
67+
========== ========== ========================== ============== ================= ======
68+
CPU Multiply FPU Integer divide 64-bit load/store Atomic
69+
========== ========== ========================== ============== ================= ======
70+
archs mpy none \+ \+ \+
71+
hs none none \- \- \-
72+
hs34 mpy none \- \- \+
73+
hs38 plus_qmacw none \+ \+ \+
74+
hs38_linux plus_qmacw DP FPU with all extensions \+ \+ \+
75+
========== ========== ========================== ============== ================= ======
76+
77+
.. note::
78+
79+
Note that if you use TCF to provide target options, there are no checks that
80+
option values are consistent with CPU and you can specify there values that
81+
are weaker than CPU value requires. So please be careful when editing TCFs.
82+
83+
Other options and TCF
84+
---------------------
85+
86+
* Endianness is set when you choose a toolchain for your project and can not be
87+
changed.
88+
* Other architecture options you can either set manually or choose a TCF file
89+
for used CPU core (available only for ARC EM and HS), which will set these options
90+
automatically. The only option that is not set automatically by selecting
91+
a TCF file is **ABI selection** option, which is available only for ARC HS processors.
92+
93+
.. figure:: images/building/target_tcf_selected.png
94+
95+
Target Processor Page for ARC HS with TCF checkbox selected
96+
97+
It is recommended to use TCF files, because they are generated from the Build
98+
Configuration Registers and thus most reliably describe target core.
99+
TCF files are provided by your chip designer.
100+
101+
To see which options are set automatically if TCF is chosen, you can select a
102+
tool from the list on the left of the dialog and see the list of options to be
103+
passed to this tool in the **All options** field.
104+
105+
.. figure:: images/building/compiler_options_list.png
106+
107+
List of all the options to be passed to compilerx
108+
109+
If **TCF** is selected, **Use memory map from TCF** checkbox becomes enabled.
110+
If you check **Use memory map from TCF** box, memory map from TCF file will be
111+
passed to the linker.
112+
113+
Note that templates from **AXS10x Projects** and **EM Starter Kit Projects**
114+
already contain memory maps that are used if no other is provided. However,
115+
this is true only for **Hello World for EM SK** and **Empty Project For**
116+
templates, but not **Empty Project** ones. **Empty Project** templates are
117+
generated automatically by Eclipse and do not contain any specific information.
118+
119+
.. figure:: images/creating_project/memory_map.png
120+
121+
Memory map for **Hello World for EM SK 2.1 Project**

‎doc/ide/creating-a-debug-configuration.rst‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
.. _creating-a-debug-configuration:
2+
3+
Creating a Debug Configuration
4+
==============================
5+
6+
Creating a new debug configuration
7+
----------------------------------
8+
9+
Once the C Project is successfully compiled by ARC GCC, you can debug the
10+
resulting executable on a board or using nSIM.
11+
12+
To debug the project, create a new debug configuration.
13+
14+
1. Select **Debug Configurations** from the **Run** menu or by clicking on
15+
the down arrow next to the bug icon:
16+
17+
.. figure:: images/debugging/debug_configurations.png
18+
19+
Debug Configurations
20+
21+
2. Double click on the **ARC C/C++ Application** or click on the top left icon
22+
to create a new debug configuration for the project:
23+
24+
.. figure:: images/debugging/arc_debug_configurations.png
25+
26+
ARC Embedded Debug Configurations
27+
28+
3. Select a name for the new debug configuration (by default, it equals the
29+
project name followed by "Debug").
30+
31+
.. figure:: images/debugging/openocd/debug_configuration.png
32+
33+
New debug Configuration
34+
35+
4. Click the **Debugger** tab.
36+
37+
.. figure:: images/debugging/debugger_tab_default.jpg
38+
39+
Default values in the Debugger tab for JTAG via OpenOCD
40+
41+
Here you can select a GDB server you want to use. About different GDB servers
42+
and their settings see pages
43+
44+
* `Debugging with OpenOCD <debugging-with-openocd>`
45+
* `Debugging with Opella-XD <debugging-with-opellaxd>`
46+
* `Debugging with nSIM <debugging-with-nsim>`
47+
* `Debugging using custom GDB server <debugging-with-custom-gdb-server>`
48+
* `Using running GDB server <debugging-with-running-gdb-server>`
49+
50+
.. note::
51+
There is a known problem with changing **ARC GDB Server**'s value on
52+
Ubuntu. After changing the value there are only two fields visible: **ARC GDB
53+
Server** and **Port number**. Workaround: select GDB server's value,
54+
press **Apply** button, then close and open the dialog again. After that all
55+
the necessary fields become visible.
56+
57+
.. _setting-a-com-port:
58+
59+
Setting a COM port
60+
------------------
61+
62+
If you are debugging an application on a board you need to specify a COM port
63+
to connect to. Open the **Terminal** tab.
64+
65+
.. figure:: images/debugging/openocd/com_port.png
66+
67+
Terminal Tab
68+
69+
The **COM Ports** picklist shows the value for Digilent
70+
USB Serial Port from the Windows registry. You can modify the value as
71+
desired, but the selection must match the port number in Device and
72+
Printers as shown in below.
73+
74+
.. figure:: images/debugging/serial_port_window.png
75+
76+
Digilent USB Serial COM Port
77+
78+
79+
Starting a debug session
80+
------------------------
81+
82+
1. Click the **Debug** button in the **Debug configurations** dialog or **Debug**
83+
button of IDE to initiate debug session.
84+
85+
This action automatically launches your GDB server (if you are not connecting to
86+
a running one). If you are using a board, it also launches the Serial terminal
87+
and connects to your board.
88+
89+
90+
2. Click **Yes** in the confirmation dialog to switch to the Debug perspective.
91+
92+

0 commit comments

Comments
 (0)