How-To

⌘K
  2. Home
  4. Docs
  6. How-To
  8. Make a Pre-built Array Topology File

Make a Pre-built Array Topology File

Inter-array communication in Hexabitz is done using a routing table stored in a special header (.h) file. This header file describes the number of modules and how they are connected to each other as well as other important information for the array; hence it is called a topology header file. Currently, you need to make a topology file manually (by modifying an existing one) or ask the array to generate it dynamically by the explore command and API. Later, we might provide a software tool to generate topology files, especially for complex arrays. Yet, it is still a good practice to go through creating a topology file for a simple array to help you understand the process.

An example topology header file is available here. It represents the array below.

Topology Test Array

 

What is inside a topology header file?

Let’s have a look in-depth into a topology header file for an 8-module array.

  • File name and version comment block: Do some modifications to identify your file. It has no effect on operation.
/*
    BitzOS (BOS) V0.0.0 - Copyright (C) 2017 Hexabitz
    All rights reserved

    File Name     : topology_1.h
    Description   : Array topology definition.
*/
  • Prevent recursive inclusion of this file: Replace your file name after #ifndef and #define.
/* Define to prevent recursive inclusion -------------------------------------*/
#ifndef __topology_1_H
#define __topology_1_H
#ifdef __cplusplus
 extern "C" {
#endif
  • Define number of modules in the array (only programmable modules).
#define _N    8                    // Number of array modules
  • Define module IDs: Add one line for each programmable module in the array. IDs must be sequential.
// Array modules
#define _mod1	1<<3
#define _mod2	2<<3
#define _mod3	3<<3
#define _mod4	4<<3
#define _mod5	5<<3
#define _mod6	6<<3
#define _mod7	7<<3
#define _mod8	8<<3
  • Array topology (routing table): Do modifications based on your array shape and configuration. Each line expresses  a single module. The first value represents the module PN (remark the underscore in the beginning). The next six values represent the six array ports of a hexagon. When a value is 0, it means the module port is not connected. The value of _modx|Py means this port is connected to port Py of module x. For example, last value in module 1 line means that P6 of module 1 is connected to P4 of module 3.
// Topology
static uint16_t array[_N][7] = {
{ _H01R0, 0, 0, 0, _mod2|P5, 0, _mod3|P4},			// Module 1
{ _H01R0, 0, 0, _mod4|P6, 0, _mod1|P4, 0},			// Module 2
{ _H01R0, 0, 0, 0, _mod1|P6, 0, _mod5|P3},			// Module 3
{ _H01R0, 0, 0, _mod6|P6, _mod7|P6, 0, _mod2|P3},		// Module 4
{ _H01R0, 0, 0, _mod3|P6, 0, _mod7|P4, _mod8|P3},		// Module 5
{ _H01R0, 0, 0, 0, 0, _mod7|P1, _mod4|P3},			// Module 6
{ _H01R0, _mod6|P5, 0, _mod8|P4, _mod5|P5, 0, _mod4|P4},	// Module 7
{ _H01R0, 0, 0, _mod5|P6, _mod7|P3, 0, 0}			// Module 8
};
  • Port directions for duplex communication: As mentioned in the hardware architecture here, array ports’ default configuration is TXD on top and RXD on bottom in order to achieve full modularity. However, ports cannot be connected before swapping the polarity on one of them (since the TXD of one port should connect to the RXD of the other one and vice versa) unless single-line, half duplex communication is desired. You should add a similar section to define port swap status for each programmable module. The first line defines module PN (remark the absence of underscore here). Subsequent lines define port polarity. normal is the default configuration (TXD top and RXD bottom) while reversed is the other way (RXD top and TXD bottom). Note that only one of the two connected ports must be reversed. It’s also preferable to leave all the unconnected ports to normal configuration. Usually, we start with module 1 by declaring all its ports as normal, and then proceed to its neighbors declaring upstream ports normal and downstream ones reversed.
// Configurations for duplex serial ports
#if ( _module == 1 )
	#define	H01R0	1
	#define	_P1pol_normal	1
	#define	_P2pol_normal	1
	#define	_P3pol_normal	1
	#define	_P4pol_normal	1	
	#define	_P5pol_normal	1
	#define	_P6pol_normal	1
#endif
#if ( _module == 2 )
	#define	H01R0	1
	#define	_P1pol_normal	1
	#define	_P2pol_normal	1
	#define	_P3pol_normal	1
	#define	_P4pol_normal	1	
	#define	_P5pol_reversed	1
	#define	_P6pol_normal	1
#endif

How to enable/disable a topology file?

You can add the topology header file to your project by uncommenting its #include directive in project.h and replacing it with the file name:

/* Array topology */
#include <topology_1.h>

Modules can then be added to the same project using uVision Targets feature. Click on Manage Project Items >> New (insert) Project Targets and name them with module IDs to identify them. You can choose the current target from the Select Target drop-down menu. One important step after that is to go to each target and modify the following:

  • Options for Target >> C/C++ >> Define Preprocessor Symbols: Modify H01R0 to module PN and _module=1 to module ID.
  • Options for Target >> Output >> Name of Executable: Modify to match module ID.

Once done, you can click on Batch Build and select all modules then Rebuild them all. We suggest to always do batch rebuild (and not build) before loading the code to make sure you don’t load an old one.

 

How can we help?

0