banjo教程
本文档是zircon驱动开发套件[Zircon Driver Development Kit]文档的一部分内容。
总览
Banjo是一个转换编码器。一个将fidl定义的接口语言转换成目标语言的程序（例如*.fidl转换成*.c,*.cpp,*.java等）。
详细内容可以参考：
https://fuchsia.googlesource.com/fuchsia/+/master/docs/development/languages/fidl/README.md。
本教程由以下内容构成：
- Banjo简要概述
- 简单示例（I2C）
- 解释从示例到生成代码
同时，这里还包含一些参考，比如：一些内建关键字和原始类型。
概述
Banjo同时生成协议制定者和协议使用者的C和C++代码。
示例
第一步，让我们来看一个相对简单的Banjo规范。在文件中zircon/system/banjo/ddk-protocol-i2c/i2c.banjo。
具体代码如下：
[01] // Copyright 2018 The Fuchsia Authors. All rights reserved.
[02] // Use of this source code is governed by a BSD-style license that can be
[03] // found in the LICENSE file.
[04]
[05] library ddk.protocol.i2c;
[06]
[07] using zx;
[08]
[09] const uint32 I2C_10_BIT_ADDR_MASK = 0xF000;
[10] const uint32 I2C_MAX_RW_OPS = 8;
[11]
[12] /// See `Transact` below for usage.
[13] struct I2cOp {
[14] vector<voidptr> data;
[15] bool is_read;
[16] bool stop;
[17] };
[18]
[19] [Layout = "ddk-protocol"]
[20] protocol I2c {
[21] /// Writes and reads data on an i2c channel. Up to I2C_MAX_RW_OPS operations can be passed in.
[22] /// For write ops, i2c_op_t.data points to data to write. The data to write does not need to be
[23] /// kept alive after this call. For read ops, i2c_op_t.data is ignored. Any combination of reads
[24] /// and writes can be specified. At least the last op must have the stop flag set.
[25] /// The results of the operations are returned asynchronously via the transact_cb.
[26] /// The cookie parameter can be used to pass your own private data to the transact_cb callback.
[27] [Async]
[28] Transact(vector<I2cOp> op) -> (zx.status status, vector<I2cOp> op);
[29] /// Returns the maximum transfer size for read and write operations on the channel.
[30] GetMaxTransferSize() -> (zx.status s, usize size);
[31] GetInterrupt(uint32 flags) -> (zx.status s, handle<interrupt> irq);
[32] };
该文件定义了一个允许应用程序通过I2C总线读写数据的接口。在I2C总线中，必须先写数据到设备请求应答。如果得到了应答，那么就可以从设备读取数据了。
我们来一行一行地看一下这些代码：
第5行，`library`直接告诉Banjo编译器需要添加什么前缀到输出的产物。可以认为它是一个域名识别符。
第7行，`using`直接告诉Banjo编译器去包含’zx’库。
第9~10行，会被程序使用到的两个常量。
第13~17行，定义了一个`I2cOp`结构体，程序会使用该结构体完成和总线的数据发送和接收。
第19~32行，定义了Banjo规范的接口方法。我们会在接口部分内容做更详细的介绍。
不要被21~26行的注释困惑了，它仅仅是注释而已，只不过它用了“///”，普通注释是“//”。它将被生成到目标源码中。在目标源码中“///”会变成“//”。
操作结构
在我们I2C例子中，结构体`struct I2cOp`定义了以下三个元素：
|
元素 |
类型 |
使用 |
|
Data |
Vector<voidptr> |
包含发送到总线，并且可以从总线接收的数据 |
|
Is_read |
Bool |
表示读取功能所需的标志 |
|
Stop |
Bool |
操作后应该发送一个表示停止字节所需的标志 |
该结构定义了通信区域，应用于协议实现者（通常是驱动程序）和协议使用者（使用总线的应用程序）。
接口
更有趣的部分内容是’protocol’规范。
我们现在将会跳过19行的`[Layout]`，和27行的`[Async]`属性，不过在后面专讲属性[Attributes]的时候，会反回到这两项内容。
本协议定义了三个接口方法：
* `Transact` ——办理
* `GetMaxTransferSize` ——获取最大传输大小
* `GetInterrupt` ——获取中断
这里并没详细讲解I2C内部操作（毕竟不是I2C总线的教程），直接看他们怎样转换成目标语言的。
我们会分开查看c和c++的实现，使用c语言描述包含结构体的定义和c++是相同的。
>现在支持生成c和c++语言代码，计划将来支持RUST语言。
banjo对应的c语言版本
c语言的实现相对比较直接了当：
* `struct`s和`union`s几乎直接映射到他们的C语言对应关键字
* `enum`s和常量生成为`#define`宏
* `protocol`s生成为两个`struct`s
1、a function table——函数功能表
2、一个指向函数表和上下文的结构体指针
* 也会生成一些辅助函数
c语言版本的文件生成在：
`//zircon/build-`_TARGET_`/system/banjo/ddk-protocol-i2c/gen/include/ddk/protocol/i2c.h`。TARGET是目标架构，比如arm64,x86等。
文件范例
本范例比较长，我们分几个部分来查看。
第一部分，样版头，我们看到之前说的”///”变成了”//”。
[01] // Copyright 2018 The Fuchsia Authors. All rights reserved.
[02] // Use of this source code is governed by a BSD-style license that can be
[03] // found in the LICENSE file.
[04]
[05] // WARNING: THIS FILE IS MACHINE GENERATED. DO NOT EDIT.
[06] // MODIFY system/banjo/ddk-protocol-i2c/i2c.banjo INSTEAD.
[07]
[08] #pragma once
[09]
[10] #include <zircon/compiler.h>
[11] #include <zircon/types.h>
[12]
[13] __BEGIN_CDECLS
第二部分，进一步声明结构体和函数。
[15] // Forward declarations
[16]
[17] typedef struct i2c_op i2c_op_t;
[18] typedef struct i2c_protocol i2c_protocol_t;
[19] typedef void (*i2c_transact_callback)(void* ctx, zx_status_t status, const i2c_op_t* op_list, size_t op_count);
[20]
[21] // Declarations
[22]
[23] // See `Transact` below for usage.
[24] struct i2c_op {
[25] const void* data_buffer;
[26] size_t data_size;
[27] bool is_read;
[28] bool stop;
[29] };
注意第17~19行，只声明了类型，并没有定义实际的结构体和该协议类型的函数。
注意文件*.banjo的第12行，经过编译转换后，到生成文件（这里是*.h）的第23行。原banjo文件被去掉了一个’/’符号，使得生成的文件的注释符合常规格式。
生成文件的第24~29行，结构体struct i2c_op几乎是从原banjo文件直接复制映射过来的。
精明的C程序员将立即看到如何在C中处理C ++样式`vector <voidptr> data`（原始`.banjo`文件行`[14]`）：它被转换为指针（“`data_buffer`”）和大小（“`data_size`”）。
以命名而言，基础名字是data（由banjo文件提供）。对于voidptr的向量，转译器增加了”_buffer”和”_size”，将向量转换成c语言兼容的结构体。对于其他向量类型，转译器增加”_list”和”_count”作为替换。
第三部分，常量。
接下来，我们看到`const uint32`常量转换成了`#define`语句。如下：
[31] #define I2C_MAX_RW_OPS UINT32_C(8)
[32]
[33]#define I2C_10_BIT_ADDR_MASK UINT32_C(0xF000)
在c语言版本中，我们选择`#define`替换`const uint32_t`的原因：
- `#define`语句只存在于编译时间，在使用的地方会被内联使用。
- `#define`允许在编译时间做优化处理。（比如，使用常量做数学运算）
缺点是我们没有类型安全性，这就是你看到辅助宏的原因（比如上面的，UINT32_C()）。他们只是将常量转换为适当的类型。
第四部分，协议结构体。
现在进入关键内容：
[35] typedef struct i2c_protocol_ops {
[36] void (*transact)(void* ctx, const i2c_op_t* op_list, size_t op_count, i2c_transact_callback callback, void* cookie);
[37] zx_status_t (*get_max_transfer_size)(void* ctx, size_t* out_size);
[38] zx_status_t (*get_interrupt)(void* ctx, uint32_t flags, zx_handle_t* out_irq);
[39] } i2c_protocol_ops_t;
`typedef`创建了一个包含三个协议方法的结构体定义，这些协议方法是我们之前在banjo文件中定义的，见原banjo文件的第28，30，31行。
注意已经发生重整的名字。这个可以让你怎样把协议方法名字和c语言函数指针映射关系对应起来，以便于知道他们调用的什么。
下一步，接口定义封装在上下文结构中，
[41] struct i2c_protocol {
[42] i2c_protocol_ops_t* ops;
[43] void* ctx;
[44] };
现在，banjo中21~26行的注释变得更有意义。
[46] // Writes and reads data on an i2c channel. Up to I2C_MAX_RW_OPS operations can be passed in.
[47] // For write ops, i2c_op_t.data points to data to write. The data to write does not need to be
[48] // kept alive after this call. For read ops, i2c_op_t.data is ignored. Any combination of reads
[49] // and writes can be specified. At least the last op must have the stop flag set.
[50] // The results of the operations are returned asynchronously via the transact_cb.
[51] // The cookie parameter can be used to pass your own private data to the transact_cb callback.
最后，我们看到实际生成的三个方法的c语言代码：
[52] static inline void i2c_transact(const i2c_protocol_t* proto, const i2c_op_t* op_list, size_t op_count, i2c_transact_callback callback, void* cookie) {
[53] proto->ops->transact(proto->ctx, op_list, op_count, callback, cookie);
[54] }
[55] // Returns the maximum transfer size for read and write operations on the channel.
[56] static inline zx_status_t i2c_get_max_transfer_size(const i2c_protocol_t* proto, size_t* out_size) {
[57] return proto->ops->get_max_transfer_size(proto->ctx, out_size);
[58] }
[59] static inline zx_status_t i2c_get_interrupt(const i2c_protocol_t* proto, uint32_t flags, zx_handle_t* out_irq) {
[60] return proto->ops->get_interrupt(proto->ctx, flags, out_irq);
[61] }
注意`i2c_`的前缀怎么加到方法名字中的（原banjo文件的20行），这样，`Transact` 变成了`i2c_transact`等等。这是banjo文件和c语言文件之间的部分代码映射关系。
同样，`library`的名字（原banjo文件的第5行），被转译成了头文件包含路径。比如：
`library ddk.protocol.i2c` ——》 `<ddk/protocol/i2c.h>`