/*
 * Copyright (C) 2017 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
#ifndef __CROS_EC_INCLUDE_APPLICATION_H
#define __CROS_EC_INCLUDE_APPLICATION_H
#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

#ifndef __packed
#define __packed __attribute__((packed))
#endif

typedef const void * const __private;

/*
 * Typical applications are independent tasks which are directed (or at least
 * influenced) by some off-chip program. Communications with the applications
 * are initiated by that off-chip Master and are routed to the application
 * using a variety of methods.
 */

/****************************************************************************/
/*
 * Datagram API:
 *
 * Nugget OS abstracts the bus protocol (SPI, USB, whatever) into two
 * unidirectional "datagram" transactions:
 *
 * - Read (the master wants data from the application)
 * - Write (the master sends data to the application)
 *
 * Each transaction consists of a four-byte Command from the Master, plus zero
 * or more data bytes either to (Read) or from (Write) the Master.
 *
 * The Command indicates the direction of data transfer, the application it
 * addresses, and various other parameters. The application is responsible for
 * providing (Read) or accepting (Write) the data bytes.
 *
 * Note: This interface was first used on the SPI bus, which allows for
 * simultaneous bidirectional data transfer. We limit this interface to
 * unidirectional transfers, because none of the other buses support that
 * feature.
 */

/****************************************************************************/
/* Application IDs */

/* These two App IDs shouldn't be changed or used for other purposes */
#define APP_ID_NUGGET            0x00    /* because we're selfish */
#define APP_ID_TPM_REGISTER_API  0xD4    /* mandated by the TCG */
/*
 * Other App IDs are defined here. It will help avoid confusion if you use only
 * the values from here and don't change them once they're set. But it's up to
 * you. I'm a comment, not a cop.
 */
#define APP_ID_AVB               0x01
#define APP_ID_KEYMASTER         0x02
#define APP_ID_WEAVER            0x03
#define APP_ID_PROTOBUF          0x04

/* Fake apps used only for testing */
#define APP_ID_AVB_TEST          0x11

/* This app ID should only be used by tests. */
#define APP_ID_TEST              0xff

/****************************************************************************/
/* Other command fields */

/*
 * The Command encoding is:
 *
 *   Bits 31-24   Control flags (reserved)
 *   Bits 23-16   Application ID
 *   Bits 15-0    Parameters (application-specific)
 */

/* Control flag bits */
#define CMD_IS_READ       0x80000000    /* 1=Read, 0=Write */
/* All other control flags bits are reserved */

/* Extracting fields from a command */
#define GET_APP_ID(cmd)     (((cmd) & 0x00ff0000) >> 16)
#define GET_APP_PARAM(cmd)  ((cmd) & 0x0000ffff)

/* Specifying command fields */
#define CMD_ID(id)       (((id) & 0x000000ff) << 16)
#define CMD_PARAM(p)     ((p) & 0x0000ffff)
#define CMD_SET_PARAM(cmd, p) cmd = ((cmd & 0xffff0000) | (p & 0x0000ffff))

/****************************************************************************/
/* Data transfer */

/*
 * Functions of this type are invoked when the Master wants to read bytes from
 * an application. The app should parse the Command, copy up to max_tx_size
 * bytes into the tx_buffer provided, and return the number of bytes to send
 * back to the Master.
 *
 * This is called in interrupt context, so act quickly.
 *
 * The last arg is for internal use. Just ignore it.
 */
typedef uint32_t (read_from_app_fn_t)(uint32_t command,
                                      uint8_t *tx_buffer,
                                      uint32_t max_tx_bytes,
                                      __private priv);

/*
 * Functions of this type are invoked when the Master has sent bytes to the
 * application. The app should parse the Command and copy or process the
 * expected number of bytes in the rx_buffer that the master has sent, up to
 * rx_num_bytes.
 *
 * NOTE: Due to a quirk of the Citadel hardware, up to four extra bytes from
 * the *next* transaction may be at the end of the rx_buffer. The application
 * should only poke at the bytes it expects to see and ignore any extras.
 *
 * This is called in interrupt context, so act quickly.
 *
 * The last arg is for internal use. Just ignore it.
 */
typedef void (write_to_app_fn_t)(uint32_t command,
                                 const uint8_t *rx_buffer,
                                 uint32_t num_rx_bytes,
                                 __private priv);

/*
 * For apps that run asynchronously with little oversight, occasional
 * Read/Write operations may be all that's necessary. An app that intercepts
 * button presses, an accelerometer, or a fingerprint scanner can simply be
 * told to start or stop and will send interrupts to the Master when its
 * attention is required.
 *
 * Applications are free to define their own protcols and APIs using only the
 * functions and constants above (and at least one app does just that).
 *
 * An app that wishes to handle its messaging using only the components
 * described to this point would use the following macro to declare itself.
 */

/**
 * This registers an application that communicates using the Datagram API,
 * which deals only with the raw byte streams between Master (AP) and Slave
 * (application).
 *
 * The name and version values may be exported to the Master by Nugget OS, so
 * the Master can query what applications are available without blindly trying
 * them all to see what works.
 *
 * @param  Id        The Application ID, defined above
 * @param  Name      A human-readable string identifying the application
 * @param  Version   An app-specific uint32_t number, for compability purposes
 * @param  From_fn   A pointer to the app's read_from_app_fnt_t handler
 * @param  To_fn     A pointer to the app's write_to_app_fn_t handler
 */
#define DECLARE_APPLICATION_DATAGRAM(Id, Name, Version, From_fn, To_fn) \
    const struct app_info __keep CONCAT2(app_, Id)                      \
      __attribute__((section(".rodata.app_info")))                      \
      = { .api = { .id = Id,                                            \
             .from_fn = From_fn, .to_fn = To_fn},                       \
          .version = Version, .name = Name }

/****************************************************************************/
/* Transport API */
/*
 * Rather than handle unidirectonal datagrams themselves, many applications
 * want to implement a request/response behavior, where the Master tells the
 * app to do something and waits for it to finish and return the result.
 *
 * Seen from the AP's side, the application would be invoked using a blocking
 * function something like this:
 *
 *   uint32_t call_application(uint8_t app_id, uint16_t app_param,
 *                             const uint8_t *args, uint16_t arg_len,
 *                             uint8_t *reply, uint16_t *reply_len);
 *
 * The request or response may be larger than one bus transaction, and the AP
 * may poll until the app finishes or wait for an interrupt before retrieving
 * the reply (there's no difference from app's point of view).
 *
 * With this API, the application is initially idle. Nugget OS will marshall
 * all the input from the Master before waking the application. The Application
 * then performs the requested operation and transititions to a "done" state.
 * The Master will retrieve the application status and any reply data from
 * Nugget OS, after which the application is ready to handle the next command.
 *
 * Applications that wish to use this transport API will need to declare a
 * private struct app_transport which Nugget OS can use to maintain the state:
 */

struct app_transport {
  uint32_t command;                           /* from master */
  volatile uint32_t status;                   /* current application status */
  uint8_t *request, *response;                /* input/output data buffer */
  uint16_t max_request_len, max_response_len; /* data buffer sizes */
  uint16_t request_len, response_len;         /* current buffer count */
  uint16_t request_idx, response_idx;         /* used internally */
  void (*done_fn)(struct app_transport *);    /* optional cleanup function */
  /* Note: Any done_fn() is called in interrupt context. Be quick. */
};

/*
 * TODO(b/66104849): Note that request and response buffers are transferred as
 * byte streams. However, if they will eventually represent structs, the usual
 * ABI alignment requirements will be required. Until we've declared all
 * applications structs in a union, we will need to align the buffers manually.
 * Use this to declare the uint8_t buffers until then:
 */
#define __TRANSPORT_ALIGNED__ __attribute__((aligned(8)))

/* For debugging if needed */
extern void dump_transport_state(const struct app_transport *s);

/*
 * The application will need to provide a write_to_app_fn_t function that will
 * be invoked when a new request is ready to be processed. All command and data
 * parameters will already be present in the app's struct app_transport, so it
 * just needs to awaken the application task to do the work.
 *
 * When processing is finished, the app should call the app_reply() function to
 * return its status code and specify length of any data it has placed into the
 * response buffer, and then it can go back to sleep until its next invocation.
 */
void app_reply(struct app_transport *st, uint32_t status, uint16_t reply_len);

/* Application status codes are uint32_t, but an enum is easier to read. */
enum app_status {
  /* A few values are common to all applications */
  APP_SUCCESS = 0,
  APP_ERROR_BOGUS_ARGS,      /* caller being stupid */
  APP_ERROR_INTERNAL,        /* application being stupid */
  APP_ERROR_TOO_MUCH,        /* caller sent too much data */
  APP_ERROR_IO,              /* problem sending or receiving data */
  APP_ERROR_RPC,             /* problem during RPC communication */
  /* more? */

  APP_SPECIFIC_ERROR = 0x20, /* "should be enough for anybody" */
  /* App-specific error codes can use APP_SPECIFIC_ERROR+0, +1, +2, ... */

  /* For debugging, returning a line number might be helpful */
  APP_LINE_NUMBER_BASE = 0x70000000,
#define APP_ERROR_LINENO (APP_LINE_NUMBER_BASE + __LINE__)

  /* Bit 31 is reserved for internal use */
  MAX_APP_STATUS = 0x7fffffff,
};

/**
 * This registers an application that communicates using the Transport API.
 *
 * The name and version values may be exported to the Master by Nugget OS, so
 * the Master can query what applications are available without blindly trying
 * them all to see what works.
 *
 * @param  Id        The Application ID, defined above
 * @param  Name      A human-readable string identifying the application
 * @param  Version   An app-specific uint32_t number, for compability purposes
 * @param  State     A pointer to the app's struct app_transport
 * @param  To_fn     A pointer to the app's write_to_app_fn_t handler
 */
#define DECLARE_APPLICATION_TRANSPORT(Id, Name, Version, State, To_fn)  \
    const struct app_info __keep CONCAT2(app_, Id)                      \
      __attribute__((section(".rodata.app_info")))                      \
      = { .api = { .id = Id,                                            \
             .from_fn = transaction_api_from_fn,                        \
             .to_fn = transaction_api_to_fn,                            \
             .data = &(const struct datagram_api)                       \
             { .id = Id, .to_fn = To_fn,                                \
               .data = State } },                                       \
          .version = Version, .name = Name }

/****************************************************************************/
/* Pay no attention to that man behind the curtain */

/* We'll allow 31 bits of application status. We need one bit for transport. */
#define APP_STATUS_IDLE     0x00000000    /* waiting for instructions */
#define APP_STATUS_DONE     0x80000000    /* finished, reply is ready */
#define APP_STATUS_CODE(res) ((res) & 0x7fffffff) /* actual status */

/* Datagram API needs this info */
struct datagram_api {
  uint8_t id;
  read_from_app_fn_t * const from_fn;
  write_to_app_fn_t * const to_fn;
  const void * const data;
};

/* Here's the struct that keeps track of registered applications */
struct app_info {
  struct datagram_api api;
  uint32_t version;
  const char * const name;
};

/* These handle the Transport API */
extern read_from_app_fn_t transaction_api_from_fn;
extern write_to_app_fn_t transaction_api_to_fn;

/* Command flags used internally by Transport API messages */
#define CMD_TRANSPORT       0x40000000    /* 1=Transport API message */
#define CMD_IS_DATA         0x20000000    /* 1=data msg 0=status msg */
#define CMD_MORE_TO_COME    0x10000000    /* 1=continued 0=new */

#ifdef __cplusplus
}
#endif

#endif  /* __CROS_EC_INCLUDE_APPLICATION_H */