/* * Copyright (C) 2015-2016 Intel Corporation. All rights reserved. * * This file is free software: you can redistribute it and/or modify it * under the terms of the GNU General Public License as published by the * Free Software Foundation, either version 3 of the License, or * (at your option) any later version. * * This file is distributed in the hope that it will be useful, but * WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. * See the GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program. If not, see . */ #pragma once #include #include "AP_HAL_Namespace.h" #include "utility/functor.h" #include /* * This is an interface abstracting I2C and SPI devices */ class AP_HAL::Device { public: enum BusType { BUS_TYPE_UNKNOWN = 0, BUS_TYPE_I2C = 1, BUS_TYPE_SPI = 2, BUS_TYPE_UAVCAN = 3, BUS_TYPE_SITL = 4, BUS_TYPE_MSP = 5, BUS_TYPE_SERIAL = 6, BUS_TYPE_WSPI = 7, }; enum Speed { SPEED_HIGH, SPEED_LOW, }; // Used for comms with devices that support wide SPI // like quad spi struct CommandHeader { uint32_t cmd; //Command phase data. uint32_t cfg; //Transfer configuration field. uint32_t addr; //Address phase data. uint32_t alt; // Alternate phase data. uint32_t dummy; // Number of dummy cycles to be inserted. }; FUNCTOR_TYPEDEF(PeriodicCb, void); typedef void* PeriodicHandle; // Register Read Write Callback // returns: void parameters: register address, register data, register datasize, direction R:false, W:true FUNCTOR_TYPEDEF(RegisterRWCb, void, uint8_t, uint8_t*, uint32_t, bool); typedef void* RegisterRWHandle; FUNCTOR_TYPEDEF(BankSelectCb, bool, uint8_t); Device(enum BusType type) { _bus_id.devid_s.bus_type = type; } // return bus type enum BusType bus_type(void) const { return _bus_id.devid_s.bus_type; } // return bus number uint8_t bus_num(void) const { return _bus_id.devid_s.bus; } // return 24 bit bus identifier uint32_t get_bus_id(void) const { return _bus_id.devid; } // return address on bus uint8_t get_bus_address(void) const { return _bus_id.devid_s.address; } // set device type within a device class (eg. AP_COMPASS_TYPE_LSM303D) void set_device_type(uint8_t devtype); virtual ~Device() { delete[] _checked.regs; } /* * Change device address. Note that this is the 7 bit address, it * does not include the bit for read/write. Only works on I2C */ virtual void set_address(uint8_t address) {}; /* * Set the speed of future transfers. Depending on the bus the speed may * be shared for all devices on the same bus. * * Return: true if speed was successfully set or platform doesn't implement * it; false otherwise. */ virtual bool set_speed(Speed speed) = 0; /* * Core transfer function. This does a single bus transaction which * sends send_len bytes and receives recv_len bytes back from the slave. * * Return: true on a successful transfer, false on failure. */ virtual bool transfer(const uint8_t *send, uint32_t send_len, uint8_t *recv, uint32_t recv_len) = 0; /* * Sets the required flags before transaction starts * this is to be used by Wide SPI communication interfaces like * Dual/Quad/Octo SPI */ virtual void set_cmd_header(const CommandHeader& cmd_hdr) {} /* * Sets up peripheral for execution in place mode * Only relevant for Wide SPI setup. */ virtual bool enter_xip_mode(void** map_ptr) { return false; } virtual bool exit_xip_mode() { return false; } /** * Wrapper function over #transfer() to read recv_len registers, starting * by first_reg, into the array pointed by recv. The read flag passed to * #set_read_flag(uint8_t) is ORed with first_reg before performing the * transfer. * * Return: true on a successful transfer, false on failure. */ bool read_registers(uint8_t first_reg, uint8_t *recv, uint32_t recv_len); /** * Wrapper function over #transfer() to write a byte to the register reg. * The transfer is done by sending reg and val in that order. * * Return: true on a successful transfer, false on failure. */ bool write_register(uint8_t reg, uint8_t val, bool checked=false); /* * Sets a callback to be called when a register is read or written. */ virtual void set_register_rw_callback(RegisterRWCb register_rw_callback) { _register_rw_callback = register_rw_callback; } /** * Wrapper function over #transfer() to call bank selection callback * and then invoke the transfer call * * Return: true on a successful transfer, false on failure. */ bool transfer_bank(uint8_t bank, const uint8_t *send, uint32_t send_len, uint8_t *recv, uint32_t recv_len); /** * Wrapper function over #transfer_bank() to read recv_len registers, starting * by first_reg, into the array pointed by recv. The read flag passed to * #set_read_flag(uint8_t) is ORed with first_reg before performing the * transfer. * * Return: true on a successful transfer, false on failure. */ bool read_bank_registers(uint8_t bank, uint8_t first_reg, uint8_t *recv, uint32_t recv_len); /** * Wrapper function over #transfer_bank() to write a byte to the register reg. * The transfer is done by sending reg and val in that order. * * Return: true on a successful transfer, false on failure. */ bool write_bank_register(uint8_t bank, uint8_t reg, uint8_t val, bool checked=false); /** * set a value for a checked register in a bank */ void set_checked_register(uint8_t bank, uint8_t reg, uint8_t val); /** * set a value for a checked register */ void set_checked_register(uint8_t reg, uint8_t val); /** * setup for register value checking. Frequency is how often to check registers. If set to 10 then * every 10th call to check_next_register will check a register */ bool setup_checked_registers(uint8_t num_regs, uint8_t frequency=10); /** * check next register value for correctness. Return false if value is incorrect * or register checking has not been setup */ bool check_next_register(void); // checked registers struct checkreg { uint8_t bank; uint8_t regnum; uint8_t value; }; /** * check next register value for correctness, with return of * failure value. Return false if value is incorrect or register * checking has not been setup */ bool check_next_register(struct checkreg &fail); /** * Wrapper function over #transfer() to read a sequence of bytes from * device. No value is written, differently from the #read_registers() * method and hence doesn't include the read flag set by #set_read_flag() */ bool read(uint8_t *recv, uint32_t recv_len) { return transfer(nullptr, 0, recv, recv_len); } /* * Get the semaphore for the bus this device is in. This is intended for * drivers to use during initialization phase only. */ virtual AP_HAL::Semaphore *get_semaphore() = 0; /* * Register a periodic callback for this bus. All callbacks on the * same bus are made from the same thread with lock already taken. In * other words, the callback is not executed on the main thread (or the * thread which registered the callback), but in a separate per-bus * thread. * * After registering the periodic callback, the other functions should not * be used anymore from other contexts. If it really needs to be done, the * lock must be taken. * * Return: A handle for this periodic callback. To cancel the callback * call #unregister_callback() or return false on the callback. */ virtual PeriodicHandle register_periodic_callback(uint32_t period_usec, PeriodicCb) = 0; /* * Adjust the time for the periodic callback registered with * #register_periodic_callback. Note that the time will be re-calculated * from the moment this call is made and expire after @period_usec. * * Return: true if periodic callback was successfully adjusted, false otherwise. */ virtual bool adjust_periodic_callback(PeriodicHandle h, uint32_t period_usec) = 0; /* * Cancel a periodic callback on this bus. * * Return: true if callback was successfully unregistered, false * otherwise. */ virtual bool unregister_callback(PeriodicHandle h) { return false; } /* * Sets a bank_select callback to be used for bank selection during register check */ virtual void setup_bankselect_callback(BankSelectCb bank_select) { _bank_select = bank_select; } /* * Sets a bank_select callback to be used for bank selection during register check */ virtual void deregister_bankselect_callback() { _bank_select = nullptr; } /* allows to set callback that will be called after DMA transfer complete. if this callback is set then any read/write operation will return directly after transfer setup and bus semaphore must not be released until register_completion_callback(0) called from callback itself */ virtual void register_completion_callback(AP_HAL::MemberProc proc) {} virtual void register_completion_callback(AP_HAL::Proc proc) {} /* * support for direct control of SPI chip select. Needed for * devices with unusual SPI transfer patterns that include * specific delays */ virtual bool set_chip_select(bool set) { return false; } /** * Some devices connected on the I2C or SPI bus require a bit to be set on * the register address in order to perform a read operation. This sets a * flag to be used by #read_registers(). The flag's default value is zero. */ void set_read_flag(uint8_t flag); /** * make a bus id given bus type, bus number, bus address and * device type This is for use by devices that do not use one of * the standard HAL Device types, such as UAVCAN devices */ static uint32_t make_bus_id(enum BusType bus_type, uint8_t bus, uint8_t address, uint8_t devtype); /** * return a new bus ID for the same bus connection but a new device type. * This is used for auxiliary bus connections */ static uint32_t change_bus_id(uint32_t old_id, uint8_t devtype); /** * return bus ID with a new devtype */ uint32_t get_bus_id_devtype(uint8_t devtype) const; /** * get bus type */ static enum BusType devid_get_bus_type(uint32_t dev_id); static uint8_t devid_get_bus(uint32_t dev_id); static uint8_t devid_get_address(uint32_t dev_id); static uint8_t devid_get_devtype(uint32_t dev_id); /* set number of retries on transfers */ virtual void set_retries(uint8_t retries) {}; protected: uint8_t _read_flag = 0; /* broken out device elements. The bitfields are used to keep the overall value small enough to fit in a float accurately, which makes it possible to transport over the MAVLink parameter protocol without loss of information. */ struct DeviceStructure { enum BusType bus_type : 3; uint8_t bus: 5; // which instance of the bus type uint8_t address; // address on the bus (eg. I2C address) uint8_t devtype; // device class specific device type }; union DeviceId { struct DeviceStructure devid_s; uint32_t devid; }; union DeviceId _bus_id; // set device address (eg. i2c bus address or spi CS) void set_device_address(uint8_t address) { _bus_id.devid_s.address = address; } // set device bus number void set_device_bus(uint8_t bus) { _bus_id.devid_s.bus = bus; } private: BankSelectCb _bank_select; RegisterRWCb _register_rw_callback; struct { uint8_t n_allocated; uint8_t n_set; uint8_t next; uint8_t frequency; uint8_t counter; struct checkreg last_reg_fail; struct checkreg *regs; } _checked; };