MicroBitConfig.h

00001 /*
00002 The MIT License (MIT)
00003 
00004 Copyright (c) 2016 British Broadcasting Corporation.
00005 This software is provided by Lancaster University by arrangement with the BBC.
00006 
00007 Permission is hereby granted, free of charge, to any person obtaining a
00008 copy of this software and associated documentation files (the "Software"),
00009 to deal in the Software without restriction, including without limitation
00010 the rights to use, copy, modify, merge, publish, distribute, sublicense,
00011 and/or sell copies of the Software, and to permit persons to whom the
00012 Software is furnished to do so, subject to the following conditions:
00013 
00014 The above copyright notice and this permission notice shall be included in
00015 all copies or substantial portions of the Software.
00016 
00017 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
00018 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
00019 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
00020 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
00021 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
00022 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
00023 DEALINGS IN THE SOFTWARE.
00024 */
00025 
00026 /**
00027   * Compile time configuration options for the micro:bit runtime.
00028   */
00029 
00030 #ifndef MICROBIT_CONFIG_H
00031 #define MICROBIT_CONFIG_H
00032 
00033 #include "mbed.h"
00034 #include "yotta_cfg_mappings.h"
00035 
00036 //
00037 // Memory configuration
00038 //
00039 
00040 // The start address of usable RAM memory.
00041 #ifndef MICROBIT_SRAM_BASE
00042 #define MICROBIT_SRAM_BASE                      0x20000008
00043 #endif
00044 
00045 // Physical address of the top of SRAM.
00046 #ifndef MICROBIT_SRAM_END
00047 #define MICROBIT_SRAM_END                       0x20004000
00048 #endif
00049 
00050 // The end address of memory normally reserved for Soft Device.
00051 #ifndef MICROBIT_SD_LIMIT
00052 #define MICROBIT_SD_LIMIT                       0x20002000
00053 #endif
00054 
00055 // The physical address in memory of the Soft Device GATT table.
00056 #ifndef MICROBIT_SD_GATT_TABLE_START
00057 #define MICROBIT_SD_GATT_TABLE_START            0x20001900
00058 #endif
00059 
00060 // Physical address of the top of the system stack (on mbed-classic this is the top of SRAM)
00061 #ifndef CORTEX_M0_STACK_BASE
00062 #define CORTEX_M0_STACK_BASE                    MICROBIT_SRAM_END
00063 #endif
00064 
00065 // Amount of memory reserved for the stack at the end of memory (bytes).
00066 #ifndef MICROBIT_STACK_SIZE
00067 #define MICROBIT_STACK_SIZE                     2048
00068 #endif
00069 
00070 // Physical address of the end of mbed heap space.
00071 #ifndef MICROBIT_HEAP_END
00072 #define MICROBIT_HEAP_END                       (CORTEX_M0_STACK_BASE - MICROBIT_STACK_SIZE)
00073 #endif
00074 
00075 // Defines the size of a physical FLASH page in RAM.
00076 #ifndef PAGE_SIZE
00077 #define PAGE_SIZE                               1024
00078 #endif
00079 
00080 // Defines where in memory persistent data is stored.
00081 #ifndef KEY_VALUE_STORE_PAGE
00082 #define KEY_VALUE_STORE_PAGE                    (PAGE_SIZE * (NRF_FICR->CODESIZE - 17)) 
00083 #endif
00084 
00085 #ifndef BLE_BOND_DATA_PAGE 
00086 #define BLE_BOND_DATA_PAGE                      (PAGE_SIZE * (NRF_FICR->CODESIZE - 18))
00087 #endif
00088 
00089 #ifndef DEFAULT_SCRATCH_PAGE
00090 #define DEFAULT_SCRATCH_PAGE                    (PAGE_SIZE * (NRF_FICR->CODESIZE - 19))
00091 #endif
00092 
00093 // Address of the end of the current program in FLASH memory.
00094 // This is recorded by the C/C++ linker, but the symbol name varies depending on which compiler is used.
00095 #if defined(__arm)
00096 extern uint32_t Image$$ER_IROM1$$RO$$Limit;
00097 #define FLASH_PROGRAM_END (uint32_t) (&Image$$ER_IROM1$$RO$$Limit)
00098 #else
00099 extern uint32_t __etext;
00100 #define FLASH_PROGRAM_END (uint32_t) (&__etext)
00101 #endif
00102 
00103 
00104 // Enables or disables the MicroBitHeapllocator. Note that if disabled, no reuse of the SRAM normally
00105 // reserved for SoftDevice is possible, and out of memory condition will no longer be trapped...
00106 // i.e. panic() will no longer be triggered on memory full conditions.
00107 #ifndef MICROBIT_HEAP_ALLOCATOR
00108 #define MICROBIT_HEAP_ALLOCATOR                 1
00109 #endif
00110 
00111 // Block size used by the allocator in bytes.
00112 // n.b. Currently only 32 bits (4 bytes) is supported.
00113 #ifndef MICROBIT_HEAP_BLOCK_SIZE
00114 #define MICROBIT_HEAP_BLOCK_SIZE                4
00115 #endif
00116 
00117 // The proportion of SRAM available on the mbed heap to reserve for the micro:bit heap.
00118 #ifndef MICROBIT_NESTED_HEAP_SIZE
00119 #define MICROBIT_NESTED_HEAP_SIZE               0.75
00120 #endif
00121 
00122 // If defined, reuse any unused SRAM normally reserved for SoftDevice (Nordic's memory resident BLE stack) as heap memory.
00123 // The amount of memory reused depends upon whether or not BLE is enabled using MICROBIT_BLE_ENABLED.
00124 // Set '1' to enable.
00125 #ifndef MICROBIT_HEAP_REUSE_SD
00126 #define MICROBIT_HEAP_REUSE_SD                  1
00127 #endif
00128 
00129 // The amount of memory allocated to Soft Device to hold its BLE GATT table.
00130 // For standard S110 builds, this should be word aligned and in the range 0x300 - 0x700.
00131 // Any unused memory will be automatically reclaimed as HEAP memory if both MICROBIT_HEAP_REUSE_SD and MICROBIT_HEAP_ALLOCATOR are enabled.
00132 #ifndef MICROBIT_SD_GATT_TABLE_SIZE
00133 #define MICROBIT_SD_GATT_TABLE_SIZE             0x300
00134 #endif
00135 
00136 //
00137 // Fiber scheduler configuration
00138 //
00139 
00140 // Scheduling quantum (milliseconds)
00141 // Also used to drive the micro:bit runtime system ticker.
00142 #ifndef SYSTEM_TICK_PERIOD_MS
00143 #define SYSTEM_TICK_PERIOD_MS                   6
00144 #endif
00145 
00146 //
00147 // Message Bus:
00148 // Default behaviour for event handlers, if not specified in the listen() call
00149 //
00150 // Permissable values are:
00151 //   MESSAGE_BUS_LISTENER_REENTRANT
00152 //   MESSAGE_BUS_LISTENER_QUEUE_IF_BUSY
00153 //   MESSAGE_BUS_LISTENER_DROP_IF_BUSY
00154 //   MESSAGE_BUS_LISTENER_IMMEDIATE
00155 
00156 #ifndef EVENT_LISTENER_DEFAULT_FLAGS
00157 #define EVENT_LISTENER_DEFAULT_FLAGS            MESSAGE_BUS_LISTENER_QUEUE_IF_BUSY
00158 #endif
00159 
00160 //
00161 // Maximum event queue depth. If a queue exceeds this depth, further events will be dropped.
00162 // Used to prevent message queues growing uncontrollably due to badly behaved user code and causing panic conditions.
00163 //
00164 #ifndef MESSAGE_BUS_LISTENER_MAX_QUEUE_DEPTH
00165 #define MESSAGE_BUS_LISTENER_MAX_QUEUE_DEPTH    10
00166 #endif
00167 
00168 //
00169 // Core micro:bit services
00170 //
00171 
00172 // To reduce memory cost and complexity, the micro:bit allows components to register for
00173 // periodic callback events during interrupt context, which occur every scheduling quantum (FIBER_TICK_PERIOD_MS)
00174 // This defines the maximum size of interrupt callback list.
00175 #ifndef MICROBIT_SYSTEM_COMPONENTS
00176 #define MICROBIT_SYSTEM_COMPONENTS              10
00177 #endif
00178 
00179 // To reduce memory cost and complexity, the micro:bit allows components to register for
00180 // periodic callback events when the processor is idle.
00181 // This defines the maximum size of the idle callback list.
00182 #ifndef MICROBIT_IDLE_COMPONENTS
00183 #define MICROBIT_IDLE_COMPONENTS                6
00184 #endif
00185 
00186 //
00187 // BLE options
00188 //
00189 // The BLE stack is very memory hungry. Each service can therefore be compiled in or out
00190 // by enabling/disabling the options below.
00191 //
00192 // n.b. The minimum set of services to enable over the air programming of the device will
00193 // still be brought up in pairing mode regardless of the settings below.
00194 //
00195 
00196 // Enable/Disable BLE during normal operation.
00197 // Set '1' to enable.
00198 #ifndef MICROBIT_BLE_ENABLED
00199 #define MICROBIT_BLE_ENABLED                    1
00200 #endif
00201 
00202 // Enable/Disable BLE pairing mode mode at power up.
00203 // Set '1' to enable.
00204 #ifndef MICROBIT_BLE_PAIRING_MODE
00205 #define MICROBIT_BLE_PAIRING_MODE               1
00206 #endif
00207 
00208 // Enable/Disable the use of private resolvable addresses.
00209 // Set '1' to enable.
00210 // n.b. This is known to be a feature that suffers compatibility issues with many BLE central devices.
00211 #ifndef MICROBIT_BLE_PRIVATE_ADDRESSES
00212 #define MICROBIT_BLE_PRIVATE_ADDRESSES          0
00213 #endif
00214 
00215 // Convenience option to enable / disable BLE security entirely
00216 // Open BLE links are not secure, but commonly used during the development of BLE services
00217 // Set '1' to disable all secuity
00218 #ifndef MICROBIT_BLE_OPEN
00219 #define MICROBIT_BLE_OPEN                       0
00220 #endif
00221 
00222 // Configure for open BLE operation if so configured
00223 #if (MICROBIT_BLE_OPEN == 1)
00224 #define MICROBIT_BLE_SECURITY_LEVEL             SECURITY_MODE_ENCRYPTION_OPEN_LINK
00225 #define MICROBIT_BLE_WHITELIST                  0
00226 #define MICROBIT_BLE_ADVERTISING_TIMEOUT        0
00227 #define MICROBIT_BLE_DEFAULT_TX_POWER           6
00228 #endif
00229 
00230 
00231 // Define the default, global BLE security requirements for MicroBit BLE services
00232 // May be one of the following options (see mbed's SecurityManager class implementaiton detail)
00233 // SECURITY_MODE_ENCRYPTION_OPEN_LINK:      No bonding, encryption, or whitelisting required.
00234 // SECURITY_MODE_ENCRYPTION_NO_MITM:        Bonding, encyption and whitelisting but no passkey.
00235 // SECURITY_MODE_ENCRYPTION_WITH_MITM:      Bonding, encrytion and whitelisting with passkey authentication.
00236 //
00237 #ifndef MICROBIT_BLE_SECURITY_LEVEL
00238 #define MICROBIT_BLE_SECURITY_LEVEL             SECURITY_MODE_ENCRYPTION_WITH_MITM
00239 #endif
00240 
00241 // Enable/Disable the use of BLE whitelisting.
00242 // If enabled, the micro:bit will only respond to connection requests from
00243 // known, bonded devices.
00244 #ifndef MICROBIT_BLE_WHITELIST
00245 #define MICROBIT_BLE_WHITELIST                  1
00246 #endif
00247 
00248 // Define the period of time for which the BLE stack will advertise (seconds)
00249 // Afer this period, advertising will cease. Set to '0' for no timeout (always advertise).
00250 #ifndef MICROBIT_BLE_ADVERTISING_TIMEOUT
00251 #define MICROBIT_BLE_ADVERTISING_TIMEOUT        0
00252 #endif
00253 
00254 // Defines default power level of the BLE radio transmitter.
00255 // Valid values are in the range 0..7 inclusive, with 0 being the lowest power and 7 the highest power.
00256 // Based on trials undertaken by the BBC, the radio is normally set to its lowest power level
00257 // to best protect children's privacy.
00258 #ifndef MICROBIT_BLE_DEFAULT_TX_POWER
00259 #define MICROBIT_BLE_DEFAULT_TX_POWER           0
00260 #endif
00261 
00262 // Enable/Disable BLE Service: MicroBitDFU
00263 // This allows over the air programming during normal operation.
00264 // Set '1' to enable.
00265 #ifndef MICROBIT_BLE_DFU_SERVICE
00266 #define MICROBIT_BLE_DFU_SERVICE                1
00267 #endif
00268 
00269 // Enable/Disable availability of Eddystone URL APIs
00270 // Set '1' to enable.
00271 #ifndef MICROBIT_BLE_EDDYSTONE_URL
00272 #define MICROBIT_BLE_EDDYSTONE_URL               1
00273 #endif
00274 
00275 // Enable/Disable availability of Eddystone UID APIs
00276 // Set '1' to enable.
00277 #ifndef MICROBIT_BLE_EDDYSTONE_UID
00278 #define MICROBIT_BLE_EDDYSTONE_UID               0
00279 #endif
00280 
00281 // Enable/Disable BLE Service: MicroBitEventService
00282 // This allows routing of events from the micro:bit message bus over BLE.
00283 // Set '1' to enable.
00284 #ifndef MICROBIT_BLE_EVENT_SERVICE
00285 #define MICROBIT_BLE_EVENT_SERVICE              1
00286 #endif
00287 
00288 // Enable/Disable BLE Service: MicroBitDeviceInformationService
00289 // This enables the standard BLE device information service.
00290 // Set '1' to enable.
00291 #ifndef MICROBIT_BLE_DEVICE_INFORMATION_SERVICE
00292 #define MICROBIT_BLE_DEVICE_INFORMATION_SERVICE 1
00293 #endif
00294 
00295 //
00296 // Accelerometer options
00297 //
00298 
00299 // Enable this to read 10 bits of data from the acclerometer.
00300 // Otherwise, 8 bits are used.
00301 // Set '1' to enable.
00302 #ifndef USE_ACCEL_LSB
00303 #define USE_ACCEL_LSB                           0
00304 #endif
00305 
00306 //
00307 // Display options
00308 //
00309 
00310 // Selects the matrix configuration for the display driver.
00311 // Known, acceptable options are:
00312 //
00313 #define MICROBUG_REFERENCE_DEVICE               1
00314 #define MICROBIT_3X9                            2
00315 #define MICROBIT_SB1                            3
00316 #define MICROBIT_SB2                            4
00317 
00318 #ifndef MICROBIT_DISPLAY_TYPE
00319 #define MICROBIT_DISPLAY_TYPE                   MICROBIT_SB2
00320 #endif
00321 
00322 // Selects the minimum permissable brightness level for the device
00323 // in the region of 0 (off) to 255 (full brightness)
00324 #ifndef MICROBIT_DISPLAY_MINIMUM_BRIGHTNESS
00325 #define MICROBIT_DISPLAY_MINIMUM_BRIGHTNESS     1
00326 #endif
00327 
00328 // Selects the maximum permissable brightness level for the device
00329 // in the region of 0 (off) to 255 (full brightness)
00330 #ifndef MICROBIT_DISPLAY_MAXIMUM_BRIGHTNESS
00331 #define MICROBIT_DISPLAY_MAXIMUM_BRIGHTNESS     255
00332 #endif
00333 
00334 // Selects the default brightness for the display
00335 // in the region of zero (off) to 255 (full brightness)
00336 #ifndef MICROBIT_DISPLAY_DEFAULT_BRIGHTNESS
00337 #define MICROBIT_DISPLAY_DEFAULT_BRIGHTNESS     MICROBIT_DISPLAY_MAXIMUM_BRIGHTNESS
00338 #endif
00339 
00340 // Selects the default scroll speed for the display.
00341 // The time taken to move a single pixel (ms).
00342 #ifndef MICROBIT_DEFAULT_SCROLL_SPEED
00343 #define MICROBIT_DEFAULT_SCROLL_SPEED           120
00344 #endif
00345 
00346 // Selects the number of pixels a scroll will move in each quantum.
00347 #ifndef MICROBIT_DEFAULT_SCROLL_STRIDE
00348 #define MICROBIT_DEFAULT_SCROLL_STRIDE          -1
00349 #endif
00350 
00351 // Selects the time each character will be shown on the display during print operations.
00352 // The time each character is shown on the screen  (ms).
00353 #ifndef MICROBIT_DEFAULT_PRINT_SPEED
00354 #define MICROBIT_DEFAULT_PRINT_SPEED            400
00355 #endif
00356 
00357 //Configures the default serial mode used by serial read and send calls.
00358 #ifndef MICROBIT_DEFAULT_SERIAL_MODE
00359 #define MICROBIT_DEFAULT_SERIAL_MODE            SYNC_SLEEP
00360 #endif
00361 
00362 //
00363 // File System configuration defaults
00364 //
00365 
00366 //
00367 // Defines the logical block size for the file system.
00368 // Must be a factor of the physical PAGE_SIZE (ideally a power of two less).
00369 //
00370 #ifndef MBFS_BLOCK_SIZE     
00371 #define MBFS_BLOCK_SIZE     256
00372 #endif
00373 
00374 //
00375 // FileSystem writeback cache size, in bytes. Defines how many bytes will be stored
00376 // in RAM before being written back to FLASH. Set to zero to disable this feature.
00377 // Should be <= MBFS_BLOCK_SIZE.
00378 //
00379 #ifndef MBFS_CACHE_SIZE
00380 #define MBFS_CACHE_SIZE     16
00381 #endif
00382 
00383 //
00384 // I/O Options
00385 //
00386 
00387 
00388 //
00389 // Define the default mode in which the digital input pins are configured.
00390 // valid options are PullDown, PullUp and PullNone.
00391 //
00392 #ifndef MICROBIT_DEFAULT_PULLMODE
00393 #define MICROBIT_DEFAULT_PULLMODE                PullDown
00394 #endif
00395 
00396 //
00397 // Panic options
00398 //
00399 
00400 // Enable this to invoke a panic on out of memory conditions.
00401 // Set '1' to enable.
00402 #ifndef MICROBIT_PANIC_HEAP_FULL
00403 #define MICROBIT_PANIC_HEAP_FULL                1
00404 #endif
00405 
00406 //
00407 // Debug options
00408 //
00409 
00410 // Enable this to route debug messages through the USB serial interface.
00411 // n.b. This also disables the user serial port 'uBit.serial'.
00412 // Set '1' to enable.
00413 #ifndef MICROBIT_DBG
00414 #define MICROBIT_DBG                            0
00415 #endif
00416 
00417 // Enable this to receive diagnostic messages from the heap allocator via the USB serial interface.
00418 // n.b. This requires MICROBIT_DBG to be defined.
00419 // Set '1' to enable.
00420 #ifndef MICROBIT_HEAP_DBG
00421 #define MICROBIT_HEAP_DBG                       0
00422 #endif
00423 
00424 // Versioning options.
00425 // We use semantic versioning (http://semver.org/) to identify differnet versions of the micro:bit runtime.
00426 // Where possible we use yotta (an ARM mbed build tool) to help us track versions.
00427 // if this isn't available, it can be defined manually as a configuration option.
00428 //
00429 #ifndef MICROBIT_DAL_VERSION
00430 #define MICROBIT_DAL_VERSION                    "unknown"
00431 #endif
00432 
00433 
00434 //
00435 // Helper macro used by the micro:bit runtime to determine if a boolean configuration option is set.
00436 //
00437 #define CONFIG_ENABLED(X) (X == 1)
00438 #define CONFIG_DISABLED(X) (X != 1)
00439 
00440 #if CONFIG_ENABLED(MICROBIT_HEAP_ALLOCATOR)
00441 #include "MicroBitHeapAllocator.h"
00442 #endif
00443 
00444 #if CONFIG_ENABLED(MICROBIT_DBG)
00445 extern RawSerial* SERIAL_DEBUG;
00446 #endif
00447 
00448 #endif