osd-contiki/cpu/cc26xx-cc13xx/rf-core/rf-core.h

/*
 * Copyright (c) 2015, Texas Instruments Incorporated - http://www.ti.com/
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 * 3. Neither the name of the copyright holder nor the names of its
 *    contributors may be used to endorse or promote products derived
 *    from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
 * FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
 * COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 * OF THE POSSIBILITY OF SUCH DAMAGE.
 */
/*---------------------------------------------------------------------------*/
/**
 * \addtogroup cc26xx
 * @{
 *
 * \defgroup rf-core CC13xx/CC26xx RF core
 *
 * Different flavours of chips of the CC13xx/CC26xx family have different
 * radio capability. For example, the CC2650 can operate in IEEE 802.15.4 mode
 * at 2.4GHz, but it can also operate in BLE mode. The CC1310 only supports
 * sub-ghz mode.
 *
 * However, there are many radio functionalities that are identical across
 * all chips. The rf-core driver provides support for this common functionality
 *
 * @{
 *
 * \file
 * Header file for the CC13xx/CC26xx RF core driver
 */
/*---------------------------------------------------------------------------*/
#ifndef RF_CORE_H_
#define RF_CORE_H_
/*---------------------------------------------------------------------------*/
#include "contiki-conf.h"
#include "rf-core/api/common_cmd.h"

#include <stdint.h>
#include <stdbool.h>
/*---------------------------------------------------------------------------*/
/* The channel to use in IEEE or prop mode. */
#ifdef RF_CORE_CONF_CHANNEL
#define RF_CORE_CHANNEL RF_CORE_CONF_CHANNEL
#else
#define RF_CORE_CHANNEL 25
#endif /* RF_CORE_CONF_IEEE_MODE_CHANNEL */
/*---------------------------------------------------------------------------*/
#define RF_CORE_CMD_ERROR                     0
#define RF_CORE_CMD_OK                        1
/*---------------------------------------------------------------------------*/
/**
 * \brief A data strcuture representing the radio's primary mode of operation
 *
 * The CC13xx / CC26xx radio supports up to potentially 3 modes: IEEE, Prop and
 * BLE. Within Contiki, we assume that the radio is by default in one of IEEE
 * or Prop in order to support standard 6LoWPAN / .15.4 operation. The BLE
 * mode interrupts this so called "primary" mode in order to send BLE adv
 * messages. Once BLE is done advertising, we need to be able to restore the
 * previous .15.4 mode. Unfortunately, the only way this can be done with
 * NETSTACK_RADIO API is by fully power-cycling the radio, which is something
 * we do not want to do.
 *
 * Thus, we declare a secondary data structure for primary mode drivers (IEEE
 * or Prop). We use this data structure to issue "soft off" and "back on"
 * commands. Soft off in this context means stopping RX (e.g. the respective
 * IEEE RX operation), but without shutting down the RF core (which is what
 * NETSTACK_RADIO.off() would have done). We then remember what mode we were
 * using in order to be able to re-enter RX mode for this mode.
 *
 * A NETSTACK_RADIO driver will declare those two functions somewhere within
 * its module of implementation. During its init() routine, it will notify
 * the RF core module so that the latter can abort and restore operations.
 */
typedef struct rf_core_primary_mode_s {
  /**
   * \brief A pointer to a function used to abort the current radio op
   */
  void (*abort)(void);

  /**
   * \brief A pointer to a function that will restore the previous radio op
   * \return RF_CORE_CMD_OK or RF_CORE_CMD_ERROR
   */
  uint8_t (*restore)(void);
} rf_core_primary_mode_t;
/*---------------------------------------------------------------------------*/
/* RF Command status constants - Correspond to values in the CMDSTA register */
#define RF_CORE_CMDSTA_PENDING         0x00
#define RF_CORE_CMDSTA_DONE            0x01
#define RF_CORE_CMDSTA_ILLEGAL_PTR     0x81
#define RF_CORE_CMDSTA_UNKNOWN_CMD     0x82
#define RF_CORE_CMDSTA_UNKNOWN_DIR_CMD 0x83
#define RF_CORE_CMDSTA_CONTEXT_ERR     0x85
#define RF_CORE_CMDSTA_SCHEDULING_ERR  0x86
#define RF_CORE_CMDSTA_PAR_ERR         0x87
#define RF_CORE_CMDSTA_QUEUE_ERR       0x88
#define RF_CORE_CMDSTA_QUEUE_BUSY      0x89

/* Status values starting with 0x8 correspond to errors */
#define RF_CORE_CMDSTA_ERR_MASK        0x80

/* CMDSTA is 32-bits. Return value in bits 7:0 */
#define RF_CORE_CMDSTA_RESULT_MASK     0xFF

#define RF_CORE_RADIO_OP_STATUS_IDLE   0x0000
/*---------------------------------------------------------------------------*/
#define RF_CORE_NOT_ACCESSIBLE 0x00
#define RF_CORE_ACCESSIBLE     0x01
/*---------------------------------------------------------------------------*/
/* RF Radio Op status constants. Field 'status' in Radio Op command struct */
#define RF_CORE_RADIO_OP_STATUS_IDLE                     0x0000
#define RF_CORE_RADIO_OP_STATUS_PENDING                  0x0001
#define RF_CORE_RADIO_OP_STATUS_ACTIVE                   0x0002
#define RF_CORE_RADIO_OP_STATUS_SKIPPED                  0x0003
#define RF_CORE_RADIO_OP_STATUS_DONE_OK                  0x0400
#define RF_CORE_RADIO_OP_STATUS_DONE_COUNTDOWN           0x0401
#define RF_CORE_RADIO_OP_STATUS_DONE_RXERR               0x0402
#define RF_CORE_RADIO_OP_STATUS_DONE_TIMEOUT             0x0403
#define RF_CORE_RADIO_OP_STATUS_DONE_STOPPED             0x0404
#define RF_CORE_RADIO_OP_STATUS_DONE_ABORT               0x0405
#define RF_CORE_RADIO_OP_STATUS_ERROR_PAST_START         0x0800
#define RF_CORE_RADIO_OP_STATUS_ERROR_START_TRIG         0x0801
#define RF_CORE_RADIO_OP_STATUS_ERROR_CONDITION          0x0802
#define RF_CORE_RADIO_OP_STATUS_ERROR_PAR                0x0803
#define RF_CORE_RADIO_OP_STATUS_ERROR_POINTER            0x0804
#define RF_CORE_RADIO_OP_STATUS_ERROR_CMDID              0x0805
#define RF_CORE_RADIO_OP_STATUS_ERROR_NO_SETUP           0x0807
#define RF_CORE_RADIO_OP_STATUS_ERROR_NO_FS              0x0808
#define RF_CORE_RADIO_OP_STATUS_ERROR_SYNTH_PROG         0x0809

/* Additional Op status values for IEEE mode */
#define RF_CORE_RADIO_OP_STATUS_IEEE_SUSPENDED           0x2001
#define RF_CORE_RADIO_OP_STATUS_IEEE_DONE_OK             0x2400
#define RF_CORE_RADIO_OP_STATUS_IEEE_DONE_BUSY           0x2401
#define RF_CORE_RADIO_OP_STATUS_IEEE_DONE_STOPPED        0x2402
#define RF_CORE_RADIO_OP_STATUS_IEEE_DONE_ACK            0x2403
#define RF_CORE_RADIO_OP_STATUS_IEEE_DONE_ACKPEND        0x2404
#define RF_CORE_RADIO_OP_STATUS_IEEE_DONE_TIMEOUT        0x2405
#define RF_CORE_RADIO_OP_STATUS_IEEE_DONE_BGEND          0x2406
#define RF_CORE_RADIO_OP_STATUS_IEEE_DONE_ABORT          0x2407
#define RF_CORE_RADIO_OP_STATUS_ERROR_WRONG_BG           0x0806
#define RF_CORE_RADIO_OP_STATUS_IEEE_ERROR_PAR           0x2800
#define RF_CORE_RADIO_OP_STATUS_IEEE_ERROR_NO_SETUP      0x2801
#define RF_CORE_RADIO_OP_STATUS_IEEE_ERROR_NO_FS         0x2802
#define RF_CORE_RADIO_OP_STATUS_IEEE_ERROR_SYNTH_PROG    0x2803
#define RF_CORE_RADIO_OP_STATUS_IEEE_ERROR_RXOVF         0x2804
#define RF_CORE_RADIO_OP_STATUS_IEEE_ERROR_TXUNF         0x2805

/* Op status values for BLE mode */
#define RF_CORE_RADIO_OP_STATUS_BLE_DONE_OK              0x1400
#define RF_CORE_RADIO_OP_STATUS_BLE_DONE_RXTIMEOUT       0x1401
#define RF_CORE_RADIO_OP_STATUS_BLE_DONE_NOSYNC          0x1402
#define RF_CORE_RADIO_OP_STATUS_BLE_DONE_RXERR           0x1403
#define RF_CORE_RADIO_OP_STATUS_BLE_DONE_CONNECT         0x1404
#define RF_CORE_RADIO_OP_STATUS_BLE_DONE_MAXNACK         0x1405
#define RF_CORE_RADIO_OP_STATUS_BLE_DONE_ENDED           0x1406
#define RF_CORE_RADIO_OP_STATUS_BLE_DONE_ABORT           0x1407
#define RF_CORE_RADIO_OP_STATUS_BLE_DONE_STOPPED         0x1408
#define RF_CORE_RADIO_OP_STATUS_BLE_ERROR_PAR            0x1800
#define RF_CORE_RADIO_OP_STATUS_BLE_ERROR_RXBUF          0x1801
#define RF_CORE_RADIO_OP_STATUS_BLE_ERROR_NO_SETUP       0x1802
#define RF_CORE_RADIO_OP_STATUS_BLE_ERROR_NO_FS          0x1803
#define RF_CORE_RADIO_OP_STATUS_BLE_ERROR_SYNTH_PROG     0x1804
#define RF_CORE_RADIO_OP_STATUS_BLE_ERROR_RXOVF          0x1805
#define RF_CORE_RADIO_OP_STATUS_BLE_ERROR_TXUNF          0x1806

/* Op status values for proprietary mode */
#define RF_CORE_RADIO_OP_STATUS_PROP_DONE_OK             0x3400
#define RF_CORE_RADIO_OP_STATUS_PROP_DONE_RXTIMEOUT      0x3401
#define RF_CORE_RADIO_OP_STATUS_PROP_DONE_BREAK          0x3402
#define RF_CORE_RADIO_OP_STATUS_PROP_DONE_ENDED          0x3403
#define RF_CORE_RADIO_OP_STATUS_PROP_DONE_STOPPED        0x3404
#define RF_CORE_RADIO_OP_STATUS_PROP_DONE_ABORT          0x3405
#define RF_CORE_RADIO_OP_STATUS_PROP_DONE_RXERR          0x3406
#define RF_CORE_RADIO_OP_STATUS_PROP_DONE_IDLE           0x3407
#define RF_CORE_RADIO_OP_STATUS_PROP_DONE_BUSY           0x3408
#define RF_CORE_RADIO_OP_STATUS_PROP_DONE_IDLETIMEOUT    0x3409
#define RF_CORE_RADIO_OP_STATUS_PROP_DONE_BUSYTIMEOUT    0x340A
#define RF_CORE_RADIO_OP_STATUS_PROP_ERROR_PAR           0x3800
#define RF_CORE_RADIO_OP_STATUS_PROP_ERROR_RXBUF         0x3801
#define RF_CORE_RADIO_OP_STATUS_PROP_ERROR_RXFULL        0x3802
#define RF_CORE_RADIO_OP_STATUS_PROP_ERROR_NO_SETUP      0x3803
#define RF_CORE_RADIO_OP_STATUS_PROP_ERROR_NO_FS         0x3804
#define RF_CORE_RADIO_OP_STATUS_PROP_ERROR_RXOVF         0x3805
#define RF_CORE_RADIO_OP_STATUS_PROP_ERROR_TXUNF         0x3806

/* Bits 15:12 signify the protocol */
#define RF_CORE_RADIO_OP_STATUS_PROTO_MASK               0xF000
#define RF_CORE_RADIO_OP_STATUS_PROTO_GENERIC            0x0000
#define RF_CORE_RADIO_OP_STATUS_PROTO_BLE                0x1000
#define RF_CORE_RADIO_OP_STATUS_PROTO_IEEE               0x2000
#define RF_CORE_RADIO_OP_STATUS_PROTO_PROP               0x3000

/* Bits 11:10 signify Running / Done OK / Done with error */
#define RF_CORE_RADIO_OP_MASKED_STATUS                   0x0C00
#define RF_CORE_RADIO_OP_MASKED_STATUS_RUNNING           0x0000
#define RF_CORE_RADIO_OP_MASKED_STATUS_DONE              0x0400
#define RF_CORE_RADIO_OP_MASKED_STATUS_ERROR             0x0800
/*---------------------------------------------------------------------------*/
/* Command Types */
#define RF_CORE_COMMAND_TYPE_MASK                        0x0C00
#define RF_CORE_COMMAND_TYPE_RADIO_OP                    0x0800
#define RF_CORE_COMMAND_TYPE_IEEE_BG_RADIO_OP            0x0800
#define RF_CORE_COMMAND_TYPE_IEEE_FG_RADIO_OP            0x0C00

#define RF_CORE_COMMAND_PROTOCOL_MASK                    0x3000
#define RF_CORE_COMMAND_PROTOCOL_COMMON                  0x0000
#define RF_CORE_COMMAND_PROTOCOL_BLE                     0x1000
#define RF_CORE_COMMAND_PROTOCOL_IEEE                    0x2000
#define RF_CORE_COMMAND_PROTOCOL_PROP                    0x3000
/*---------------------------------------------------------------------------*/
/* Radio timer register */
#define RATCNT  0x00000004
/*---------------------------------------------------------------------------*/
/* Make the main driver process visible to mode drivers */
PROCESS_NAME(rf_core_process);
/*---------------------------------------------------------------------------*/
/**
 * \brief Check whether the RF core is accessible
 * \retval RF_CORE_ACCESSIBLE The core is powered and ready for access
 * \retval RF_CORE_NOT_ACCESSIBLE The core is not ready
 *
 * If this function returns RF_CORE_NOT_ACCESSIBLE, rf_core_power_up() must be
 * called before any attempt to access the core.
 */
uint8_t rf_core_is_accessible(void);

/**
 * \brief Sends a command to the RF core.
 *
 * \param cmd The command value or a pointer to a command buffer
 * \param status A pointer to a variable which will hold the status
 * \return RF_CORE_CMD_OK or RF_CORE_CMD_ERROR
 *
 * This function supports all three types of command (Radio OP, immediate and
 * direct)
 *
 * For immediate and Radio OPs, cmd is a pointer to the data structure
 * containing the command and its parameters. This data structure must be
 * 4-byte aligned.
 *
 * For direct commands, cmd contains the value of the command alongside its
 * parameters. This value will be written to CMDSTA verbatim, so the command
 * ID must be in the 16 high bits, and the 2 LS bits must be set to 01 by the
 * caller.
 *
 * The caller is responsible of allocating and populating cmd for Radio OP and
 * immediate commands
 *
 * The caller is responsible for allocating status
 *
 * For immediate commands and radio Ops, this function will set the command's
 * status field to RF_CORE_RADIO_OP_STATUS_IDLE before sending it to the RF
 */
uint_fast8_t rf_core_send_cmd(uint32_t cmd, uint32_t *status);

/**
 * \brief Block and wait for a Radio op to complete
 * \param cmd A pointer to any command's structure
 * \retval RF_CORE_CMD_OK the command completed with status _DONE_OK
 * \retval RF_CORE_CMD_ERROR Timeout exceeded or the command completed with
 *         status _DONE_xxx (e.g. RF_CORE_RADIO_OP_STATUS_DONE_TIMEOUT)
 */
uint_fast8_t rf_core_wait_cmd_done(void *cmd);

/**
 * \brief Turn on power to the RFC and boot it.
 * \return RF_CORE_CMD_OK or RF_CORE_CMD_ERROR
 */
int rf_core_power_up(void);

/**
 * \brief Disable RFCORE clock domain in the MCU VD and turn off the RFCORE PD
 */
void rf_core_power_down(void);

/**
 * \brief Initialise RF APIs in the RF core
 * \return RF_CORE_CMD_OK or RF_CORE_CMD_ERROR
 *
 * Depending on chip family and capability, this function will set the correct
 * value to PRCM.RFCMODESEL
 */
uint8_t rf_core_set_modesel(void);

/**
 * \brief Start the CM0 RAT
 * \return RF_CORE_CMD_OK or RF_CORE_CMD_ERROR
 *
 * This function must be called each time the CM0 boots. The boot sequence
 * can be performed automatically by calling rf_core_boot() if patches are not
 * required. If patches are required then the patches must be applied after
 * power up and before calling this function.
 */
uint8_t rf_core_start_rat(void);

/**
 * \brief Stop the CM0 RAT synchronously
 * \return RF_CORE_CMD_OK or RF_CORE_CMD_ERROR
 *
 * This function is not strictly necessary, but through calling it it's possibly
 * to learn the RAT / RTC offset, which useful to get accurate radio timestamps.
 */
uint8_t rf_core_stop_rat(void);

/**
 * \brief Restart the CM0 RAT
 * \return RF_CORE_CMD_OK or RF_CORE_CMD_ERROR
 *
 * This function restarts the CM0 RAT and therefore resynchornizes it with RTC.
 * To achieve good timing accuracy, it should be called periodically.
 */
uint8_t rf_core_restart_rat(void);

/**
 * \brief Boot the RF Core
 * \return RF_CORE_CMD_OK or RF_CORE_CMD_ERROR
 *
 * This function will perform the CM0 boot sequence. It will first power it up
 * and then start the RAT. If a patch is required, then the mode driver must
 * not call this function and perform the sequence manually, applying patches
 * after boot and before calling rf_core_start_rat().
 *
 * The function will return RF_CORE_CMD_ERROR if any of those steps fails. If
 * the boot sequence fails to complete, the RF Core will be powered down.
 */
uint8_t rf_core_boot(void);

/**
 * \brief Setup RF core interrupts
 */
void rf_core_setup_interrupts(bool poll_mode);

/**
 * \brief Enable interrupt on command done.
 * \param fg set true to enable irq on foreground command done and false for
 * background commands or if not in ieee mode.
 * \param poll_mode true if the driver is in poll mode
 *
 * This is used within TX routines in order to be able to sleep the CM3 and
 * wake up after TX has finished
 *
 * \sa rf_core_cmd_done_dis()
 */
void rf_core_cmd_done_en(bool fg, bool poll_mode);

/**
 * \brief Disable the LAST_CMD_DONE and LAST_FG_CMD_DONE interrupts.
 *
 * This is used within TX routines after TX has completed
 *
 * \sa rf_core_cmd_done_en()
 */
void rf_core_cmd_done_dis(bool poll_mode);

/**
 * \brief Returns a pointer to the most recent proto-dependent Radio Op
 * \return The pointer
 *
 * The RF Core driver will remember the most recent proto-dependent Radio OP
 * issued, so that other modules can inspect its type and state at a subsequent
 * stage. The assumption is that those commands will be issued by a function
 * that will then return. The following commands will be "remembered"
 *
 * - All BLE Radio Ops (0x18nn)
 * - All Prop Radio Ops (0x38nn)
 * - IEEE BG Radio Ops (0x28nn)
 *
 * The following commands are assumed to be executed synchronously and will
 * thus not be remembered by the core and not returned by this function:
 *
 * - Direct commands
 * - Proto-independent commands (including Radio Ops and Immediate ones)
 * - IEEE FG Radio Ops (0x2Cxx)
 *
 * This assumes that all commands will be sent to the radio using
 * rf_core_send_cmd()
 */
rfc_radioOp_t *rf_core_get_last_radio_op(void);

/**
 * \brief Prepare a buffer to host a Radio Op
 * \param buf A pointer to the buffer that will host the Radio Op
 * \param len The buffer's length
 * \param command The command ID
 *
 * The caller is responsible to allocate the buffer
 *
 * This function will not check whether the buffer is large enough to hold the
 * command. This is the caller's responsibility
 *
 * This function will wipe out the buffer's contents.
 */
void rf_core_init_radio_op(rfc_radioOp_t *buf, uint16_t len, uint16_t command);

/**
 * \brief Register a primary mode for radio operation
 * \param mode A pointer to the struct representing the mode
 *
 * A normal NESTACK_RADIO driver will normally register itself by calling
 * this function during its own init().
 *
 * \sa rf_core_primary_mode_t
 */
void rf_core_primary_mode_register(const rf_core_primary_mode_t *mode);

/**
 * \brief Abort the currently running primary radio op
 */
void rf_core_primary_mode_abort(void);

/**
 * \brief Abort the currently running primary radio op
 */
uint8_t rf_core_primary_mode_restore(void);
/*---------------------------------------------------------------------------*/
#endif /* RF_CORE_H_ */
/*---------------------------------------------------------------------------*/
/**
 * @}
 * @}
 */